Live2D 虚拟主播软件（开源Python）

Live2D 虚拟主播软件（开源Python）

Live2D 虚拟主播软件（开源Python）

Live2D 虚拟主播软件（开源Python）

「python制作的live2d面部捕捉（二开）」
链接：https://pan.quark.cn/s/246074fa79ed
1

Live2D Virtual Streamer

🎭 一个基于 Python 的 Live2D 虚拟主播应用程序

使用 PySide6 + MediaPipe + Live2D 技术，支持实时面部捕捉的虚拟主播系统

功能特性 • 快速开始 • 安装说明 • 使用指南 • 项目结构

</div>

📋 目录

项目简介

功能特性

系统要求

快速开始

详细安装

使用指南

配置说明

项目结构

技术架构

常见问题

开发路线

贡献指南

许可证

致谢

🎯 项目简介

Live2D Virtual Streamer 是一个功能完整的虚拟主播应用程序，通过摄像头实时捕捉用户的面部表情和头部动作，并驱动 Live2D 角色模型进行同步表演。该项目集成了：

🎨 Live2D 渲染引擎 - 支持 Cubism 2.0 和 3.0/4.0 模型

📹 实时面部捕捉 - 基于 MediaPipe Face Mesh 的高精度面部追踪

🖥️ 现代化 GUI - 使用 PySide6 构建的优雅用户界面

⚙️ 丰富配置选项 - 精细控制模型显示、捕捉参数、性能设置等

该应用程序适合虚拟主播、内容创作者、直播主以及对 Live2D 技术感兴趣的开发者使用。

✨ 功能特性

🎭 核心功能

实时面部捕捉

基于 MediaPipe Face Mesh 的高精度面部追踪

支持眼睛开合、嘴部动作、头部旋转等多维度参数捕捉

可调节的影响系数和平滑因子，实现自然的动作过渡

Live2D 模型渲染

支持 Cubism 2.0 (.moc) 和 Cubism 3.0/4.0 (.moc3) 模型格式

OpenGL 硬件加速渲染，流畅的 60FPS 动画

支持模型缩放、位置调整、旋转等变换

自动眨眼功能开关

设备管理

自动扫描和选择摄像头设备

支持多种分辨率设置（640x480 到 1920x1080）

可调节帧率（30-60 FPS）

🖼️ 显示功能

透明窗口 - 窗口透明度可调（0-100%）

置顶显示 - 窗口始终置顶选项

点击穿透 - 窗口可穿透鼠标点击

背景设置

灰色背景开关

自定义图片背景

背景图片定时刷新功能

画布边框 - 调试边框显示

🎛️ 设置面板

模型设置

加载自定义 Live2D 模型

调整模型中心点位置（X/Y）

调整模型缩放比例

调整画布尺寸

设备设置

摄像头选择和预览

分辨率和帧率设置

面部捕捉引擎选择

精度模式设置（高/中/低）

平滑因子调节

眼睛/嘴巴/头部影响系数调节

性能设置

目标 FPS 设置

性能监控

显示设置

窗口透明度

置顶开关

点击穿透开关

背景设置

边框显示

通用设置

配置重置

系统信息查看

🎨 用户界面

现代化的设置面板界面

系统托盘图标支持

右键菜单快速访问

实时预览功能

直观的参数调节滑块

中文界面支持

💻 系统要求

操作系统

✅ Windows 10/11 (x64) - 完全支持

✅ macOS (11+, ARM64 和 x64) - 完全支持

✅ Linux (Ubuntu 20.04+, Arch) - 支持

Python 版本

推荐: Python 3.10+

最低要求: Python 3.8

不支持: Python 2.x

硬件要求

CPU: 双核及以上处理器

内存: 4GB RAM 及以上（推荐 8GB+）

显卡: 支持 OpenGL 2.0+ 的显卡

摄像头: 720p 及以上网络摄像头（推荐 1080p）

磁盘空间: 至少 1GB 可用空间（包含模型文件）

🚀 快速开始

方式一：直接运行（推荐）

克隆或下载项目
复制代码
git clone https://github.com/yourusername/bbb-live2d-py-v4.git
cd bbb-live2d-py-v4
创建 Conda 环境
复制代码
# 创建名为 live2d-mascot 的 conda 环境
conda create -n live2d-mascot python=3.10

# 激活环境
conda activate live2d-mascot
安装依赖
复制代码
pip install -r examples/requirements.txt
运行程序

Windows:
复制代码
# 双击运行
run.bat

# 或命令行运行
python main.py
macOS/Linux:
复制代码
python main.py
方式二：从源码构建（高级用户）

如果需要从源码构建 Live2D C 扩展模块：
复制代码
# 1. 安装构建依赖
# Windows: 安装 Visual Studio 2019+
# macOS: 安装 Xcode Command Line Tools
# Linux: 安装 build-essential cmake

# 2. 构建项目
mkdir build && cd build
cmake ..
cmake --build .

# 3. 安装 Python 包
pip install -e .
📦 详细安装

Windows 安装

安装 Python

访问 python.org

下载 Python 3.10+ Windows installer

安装时勾选 "Add Python to PATH"

安装 Git（可选）

访问 git-scm.com

下载并安装 Git

安装 Conda（推荐）

下载 Miniconda 或 Anaconda

运行安装程序

克隆项目并安装依赖
复制代码
git clone https://github.com/yourusername/bbb-live2d-py-v4.git
cd bbb-live2d-py-v4
conda create -n live2d-mascot python=3.10 -y
conda activate live2d-mascot
pip install -r examples/requirements.txt
运行程序
复制代码
python main.py
macOS 安装

安装 Homebrew（如果未安装）
复制代码
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装 Python 和 Conda
复制代码
brew install python@3.10
brew install --cask miniconda
克隆项目并安装依赖
复制代码
git clone https://github.com/yourusername/bbb-live2d-py-v4.git
cd bbb-live2d-py-v4
conda create -n live2d-mascot python=3.10 -y
conda activate live2d-mascot
pip install -r examples/requirements.txt
运行程序
复制代码
python main.py
Linux 安装

安装系统依赖

Ubuntu/Debian:
复制代码
sudo apt update
sudo apt install -y python3.10 python3-pip python3-venv git cmake build-essential \
    libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1
Arch Linux:
复制代码
sudo pacman -S python python-pip git cmake base-devel mesa glu \
    glib2 libsm libxi libxrender
克隆项目并安装依赖
复制代码
git clone https://github.com/yourusername/bbb-live2d-py-v4.git
cd bbb-live2d-py-v4
python3.10 -m venv venv
source venv/bin/activate  # Linux
# 或 source venv/bin/activate.fish  # Fish shell
pip install -r examples/requirements.txt
运行程序
复制代码
python main.py
📖 使用指南

基本操作

启动程序

运行 python main.py 或双击 run.bat（Windows）

程序启动后会显示 Live2D 角色窗口

面部捕捉

程序会自动打开默认摄像头

面向摄像头，保持适当距离（50-100cm）

确保面部光线充足

打开设置

方法1: 右键点击 Live2D 窗口 → 选择 "设置"

方法2: 右键点击系统托盘图标 → 选择 "设置"

加载模型

打开设置面板 → "模型设置" 标签

点击 "浏览" 按钮

选择 Live2D 模型文件（.model3.json 或 .model.json）

模型会立即加载并显示

调整模型

位置: 调整 "中心 X" 和 "中心 Y" 滑块

大小: 调整 "缩放" 滑块

画布: 调整 "画布宽度" 和 "画布高度"

调整捕捉参数

打开 "设备设置" 标签

平滑因子: 控制动作平滑程度（值越大越平滑）

眼睛影响: 控制眼睛开合的敏感度

嘴巴影响: 控制嘴部动作的幅度

头部影响: 控制头部旋转的幅度

调整显示

打开 "显示设置" 标签

透明度: 调整窗口透明度（0-100%）

置顶: 勾选 "窗口置顶" 保持窗口在最前

穿透: 勾选 "点击穿透" 使鼠标点击穿透窗口

背景: 可选择灰色背景或自定义图片背景

快捷操作

右键菜单（Live2D 窗口）

设置 - 打开设置面板

重置模型 - 重置模型位置和缩放

隐藏窗口 - 隐藏主窗口

退出 - 退出程序

系统托盘图标

双击 - 显示/隐藏窗口

右键 - 显示菜单

保存配置

程序会自动保存配置到 config.json 文件，下次启动时会自动恢复上次的设置。

⚙️ 配置说明

配置文件位于项目根目录的 config.json，包含以下配置项：

画布设置
复制代码
"canvas": {
  "width": 450,              // 画布宽度
  "height": 700,             // 画布高度
  "show_border": false,      // 是否显示边框
  "show_background": false,  // 是否显示灰色背景
  "show_image_background": false,  // 是否显示图片背景
  "background_image": "background_images\\xxx.jpg"  // 背景图片路径
}
性能设置
复制代码
"performance": {
  "fps": 31  // 目标帧率
}
模型设置
复制代码
"model": {
  "center_x": 0.18,          // 模型中心 X 偏移
  "center_y": 0.11,          // 模型中心 Y 偏移
  "scale": 1.2,              // 模型缩放比例
  "current_path": "..."      // 当前模型路径
}
设备设置
复制代码
"device": {
  "camera_id": 0,            // 摄像头 ID
  "camera_width": 1280,      // 摄像头宽度
  "camera_height": 720,      // 摄像头高度
  "camera_fps": 60           // 摄像头帧率
}
面部捕捉设置
复制代码
"face": {
  "engine": "MediaPipe Face Mesh",  // 追踪引擎
  "precision": "高",                  // 精度模式
  "smooth_factor": 0.7,              // 平滑因子 (0.0-1.0)
  "eye_influence": 1.9,              // 眼睛影响系数
  "mouth_influence": 1.0,            // 嘴巴影响系数
  "head_influence": 2.0              // 头部影响系数
}
显示设置
复制代码
"display": {
  "always_on_top": true,     // 窗口置顶
  "click_through": false,    // 点击穿透
  "opacity": 100,            // 不透明度 (0-100)
  "background_enabled": false,        // 背景启用
  "background_folder": "background_images",  // 背景图片文件夹
  "background_refresh_interval": 60  // 背景刷新间隔（秒）
}
📁 项目结构
复制代码
bbb-live2d-py-v4/
├── app/                          # 主应用程序
│   ├── __init__.py
│   └── main_window.py            # 主窗口和 Live2D 渲染组件
│
├── panels/                       # 设置面板
│   ├── __init__.py
│   ├── settings_panel.py         # 设置面板主文件
│   ├── ui/                       # UI 组件
│   │   ├── config_manager.py     # 配置管理器
│   │   └── base_panel.py         # 基础面板类
│   ├── fonts/                    # 字体文件
│   └── pages/                    # 设置页面
│       ├── about_page.py         # 关于页面
│       ├── app_settings_page.py  # 应用设置页面
│       ├── device_page.py        # 设备设置页面
│       ├── display_page.py       # 显示设置页面
│       ├── general_page.py       # 通用设置页面
│       └── model_settings_page.py # 模型设置页面
│
├── examples/                     # 示例代码和资源
│   ├── main_*.py                 # 各种 GUI 框架示例
│   ├── facial_*.py               # 面部捕捉示例
│   ├── mediapipe_capture/        # MediaPipe 捕捉模块
│   ├── resources.py              # 资源路径管理
│   ├── requirements.txt          # Python 依赖
│   └── README.md                 # 示例说明
│
├── Resources/                    # Live2D 模型资源
│   ├── v2/                       # Cubism 2.0 模型
│   │   ├── haru/
│   │   ├── hibiki/
│   │   ├── shizuku/
│   │   └── ...
│   └── v3/                       # Cubism 3.0/4.0 模型
│       ├── Haru/
│       ├── Mao/
│       ├── llny/
│       └── ...
│
├── Live2D/                       # Live2D C/C++ 核心库
│   ├── Core/                     # Cubism Core
│   ├── Framework/                # Cubism Framework
│   ├── Glad/                     # OpenGL 加载器
│   └── README.md                 # Live2D 库说明
│
├── Wrapper/                      # Python C 扩展封装
│   └── (构建生成的 Python 模块)
│
├── package/                      # Python 包
│   └── live2d/
│       ├── v2/                   # Cubism 2.0 接口
│       │   └── live2d.pyi
│       └── v3/                   # Cubism 3.0/4.0 接口
│           └── live2d.pyi
│
├── background_images/            # 背景图片文件夹
│
├── cmake/                        # CMake 构建脚本
│   ├── Live2D.cmake
│   ├── Live2DViewer.cmake
│   └── Wrapper.cmake
│
├── main.py                       # 程序入口
├── config.json                   # 配置文件
├── CMakeLists.txt                # CMake 主配置
├── run.bat                       # Windows 启动脚本
├── wiki.txt                      # 项目 Wiki
├── 如何运行.txt                  # 运行说明
└── README.md                     # 本文件
🏗️ 技术架构

技术栈

层级技术组件说明

GUI 框架 PySide6 (Qt6) 现代化的跨平台 GUI 框架

OpenGL 绑定 PyOpenGL Python OpenGL 接口

3D 渲染 Live2D Cubism SDK 官方 Live2D 渲染引擎

面部追踪 MediaPipe Face Mesh Google 的面部网格检测

图像处理 OpenCV 摄像头捕获和图像处理

数值计算 NumPy 高效数值计算

C 扩展 Python C API Live2D 的 Python 绑定

构建系统 CMake 跨平台构建工具

架构图
复制代码
┌─────────────────────────────────────────────────────┐
│                   用户界面层                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ 主窗口渲染器   │  │ 设置面板      │  │ 系统托盘     │ │
│  │ Live2DWidget  │  │ SettingsPanel│  │ TrayIcon    │ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────┐
│                   业务逻辑层                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ 配置管理器     │  │ 面部捕捉器     │  │ 模型管理器   │ │
│  │ConfigManager  │  │FacialCapture │  │ModelManager │ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────┐
│                   核心引擎层                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ Live2D 引擎   │  │ MediaPipe    │  │ OpenCV      │ │
│  │ live2d.v3     │  │ Face Mesh    │  │ VideoCapture│ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────┐
│                   系统层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ OpenGL       │  │ 摄像头硬件     │  │ 文件系统     │ │
│  │ 渲染上下文     │  │ Camera Device│  │ FileSystem  │ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────┘
核心模块说明

Live2DWidget

继承自 QOpenGLWidget

负责 OpenGL 上下文初始化和 Live2D 模型渲染

处理面部参数到模型参数的映射

支持背景、边框等视觉效果

MainWindow

主应用程序窗口

管理系统托盘图标和右键菜单

集成面部捕捉定时器

协调各个组件的交互

SettingsPanel

基于对话框的设置面板

提供标签页式分类设置

实时预览和参数调整

配置保存和加载

FacialCapture

使用 MediaPipe 进行面部检测

提取 468 个面部关键点

计算眼睛开合、嘴部动作、头部旋转角度

应用平滑滤波

ConfigManager

单例模式的配置管理器

JSON 配置文件的读写

参数变更通知机制

默认值管理

❓ 常见问题

安装问题

Q: 安装 PySide6 时出现错误？

A: 确保使用最新版本的 pip：
复制代码
python -m pip install --upgrade pip
pip install PySide6
Q: MediaPipe 安装失败？

A: 使用指定版本安装：
复制代码
pip install mediapipe==0.10.21
运行问题

Q: 启动时提示 "找不到摄像头"？

A: 检查以下项目：

摄像头是否被其他程序占用

摄像头驱动是否正常安装

在设置中尝试切换摄像头 ID

Q: 模型无法加载？

A: 确认：

模型文件路径正确

模型文件完整（包含所有纹理和资源）

模型格式为 Cubism 2.0 或 3.0/4.0

Q: 面部捕捉不准确？

A: 尝试调整：

改善光线条件

调整与摄像头的距离

增大影响系数

调整平滑因子

Q: 程序运行卡顿？

A: 优化建议：

降低摄像头分辨率

降低目标 FPS

关闭不需要的背景应用

更新显卡驱动

Q: 窗口透明度不生效？

A: 某些桌面环境可能不支持窗口透明：

Windows: 通常完全支持

macOS: 完全支持

Linux: 取决于窗口管理器（KDE、GNOME 支持较好）

性能优化

Q: 如何提高性能？

A:

使用较低分辨率（640x480 或 720p）

降低 FPS 到 30

使用更简单的 Live2D 模型

关闭背景图片

使用 MediaPipe 的中/低精度模式

🗺️ 开发路线

已完成 ✅

基础 Live2D 渲染

MediaPipe 面部捕捉

PySide6 GUI 界面

设置面板

系统托盘集成

配置持久化

透明窗口支持

多种显示选项

Cubism 2.0/3.0 模型支持

计划中 🚧

更多面部表情参数（眉毛、脸颊等）

录制和回放功能

虚拟摄像头输出（OBS 集成）

多模型支持

动作录制系统

自定义表情快捷键

皮肤/主题系统

多语言支持

插件系统

自动更新功能

未来构想 💡

VR/AR 支持

全身动作捕捉

手势识别

语音识别和口型同步

AI 对话集成

云端模型库

移动端远程控制

🤝 贡献指南

欢迎任何形式的贡献！

如何贡献

Fork 本项目

创建特性分支 (git checkout -b feature/AmazingFeature)

提交更改 (git commit -m 'Add some AmazingFeature')

推送到分支 (git push origin feature/AmazingFeature)

开启 Pull Request

贡献领域

🐛 Bug 修复

✨ 新功能开发

📝 文档改进

🎨 UI/UX 优化

🌍 国际化翻译

⚡ 性能优化

🧪 测试用例

代码规范

遵循 PEP 8 Python 代码规范

添加适当的注释和文档字符串

保持函数简洁和单一职责

编写有意义的提交信息

📄 许可证

本项目基于 MIT 许可证开源 - 详见 <LICENSE> 文件

Live2D 许可

Live2D 软件：Live2D 许可协议

Cubism SDK：Cubism SDK 许可协议

使用本项目中的 Live2D 模型请遵循其各自的许可协议

第三方库许可

本项目使用的第三方库遵循其各自的许可证：

PySide6: LGPLv3

MediaPipe: Apache 2.0

OpenCV: Apache 2.0

NumPy: BSD

🙏 致谢

核心技术

Live2D - 提供了优秀的 2D 模型渲染技术

MediaPipe - Google 的强大机器学习解决方案

PySide6 - Qt 官方的 Python 绑定

OpenCV - 计算机视觉领域的标准库

项目灵感

感谢以下项目提供的灵感和参考：

live2d-py - 本项目的核心 Live2D Python 封装库

Live2D 官方示例项目

虚拟主播社区的所有开发者

特别感谢

感谢所有测试用户的反馈和建议

感谢 Live2D 社区提供的技术支持

感谢开源社区的贡献者们

📞 联系方式

问题反馈 : GitHub Issues

功能建议 : GitHub Discussions

邮件 : your.email@example.com

📸 截图

（待添加：应用程序截图展示）

🌟 Star History

如果这个项目对你有帮助，请给我们一个 ⭐️！

[⬆ 返回顶部](#⬆ 返回顶部)

Made with ❤️ by [Your Name]

</div>

层级	技术组件	说明
GUI 框架	PySide6 (Qt6)	现代化的跨平台 GUI 框架
OpenGL 绑定	PyOpenGL	Python OpenGL 接口
3D 渲染	Live2D Cubism SDK	官方 Live2D 渲染引擎
面部追踪	MediaPipe Face Mesh	Google 的面部网格检测
图像处理	OpenCV	摄像头捕获和图像处理
数值计算	NumPy	高效数值计算
C 扩展	Python C API	Live2D 的 Python 绑定
构建系统	CMake	跨平台构建工具