基于 Python 的 Live2D 虚拟主播软件

Live2D Virtual Streamer

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

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

项目简介

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 模型，调整模型中心点位置、缩放比例、画布尺寸
设备设置 - 摄像头选择和预览，分辨率和帧率设置，面部捕捉引擎选择，精度模式设置（高/中/低），平滑因子调节，眼睛/嘴巴/头部影响系数调节
性能设置 - 目标 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 环境

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 [email protected]
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" 滑块
- 大小: 调整 "缩放" 滑块
- 画布: 调整 "画布宽度" 和 "画布高度"
调整捕捉参数：打开 "设备设置" 标签，调整平滑因子、眼睛/嘴巴/头部影响系数。
调整显示：打开 "显示设置" 标签，调整透明度、置顶、穿透、背景等。

快捷操作

右键菜单（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,
    "center_y": 0.11,
    "scale": 1.2,
    "current_path": "..."
  },
  "device": {
    "camera_id": 0,
    "camera_width": 1280,
    "camera_height": 720,
    "camera_fps": 60
  },
  "face": {
    "engine": "MediaPipe Face Mesh",
    "precision": "高",
    "smooth_factor": 0.7,
    "eye_influence": 1.9,
    "mouth_influence": 1.0,
    "head_influence": 2.0
  },
  "display": {
    "always_on_top": true,
    "click_through": false,
    "opacity": 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 # 本文件

技术架构

技术栈架构图

┌─────────────────────────────────────────────────────┐
│ 用户界面层                                          │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐   │
│ │ 主窗口渲染器 │ │ 设置面板     │ │ 系统托盘   │   │
│ │ 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：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 社区提供的技术支持，感谢开源社区的贡献者们。

Live2D Virtual Streamer

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

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

项目简介

Live2D 渲染引擎 - 支持 Cubism 2.0 和 3.0/4.0 模型
实时面部捕捉 - 基于 MediaPipe Face Mesh 的高精度面部追踪
现代化 GUI - 使用 PySide6 构建的优雅用户界面
丰富配置选项 - 精细控制模型显示、捕捉参数、性能设置等

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

功能特性

核心功能

实时面部捕捉

Live2D 模型渲染

支持 Cubism 2.0 (.moc) 和 Cubism 3.0/4.0 (.moc3) 模型格式
OpenGL 硬件加速渲染，流畅的 60FPS 动画
支持模型缩放、位置调整、旋转等变换
自动眨眼功能开关

设备管理

自动扫描和选择摄像头设备
支持多种分辨率设置（640x480 到 1920x1080）
可调节帧率（30-60 FPS）

显示功能

透明窗口 - 窗口透明度可调（0-100%）
置顶显示 - 窗口始终置顶选项
点击穿透 - 窗口可穿透鼠标点击
背景设置 - 灰色背景开关，自定义图片背景，背景图片定时刷新功能
画布边框 - 调试边框显示

设置面板

模型设置 - 加载自定义 Live2D 模型，调整模型中心点位置、缩放比例、画布尺寸
设备设置 - 摄像头选择和预览，分辨率和帧率设置，面部捕捉引擎选择，精度模式设置（高/中/低），平滑因子调节，眼睛/嘴巴/头部影响系数调节
性能设置 - 目标 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 环境

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 [email protected]
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" 滑块
- 大小: 调整 "缩放" 滑块
- 画布: 调整 "画布宽度" 和 "画布高度"
调整捕捉参数：打开 "设备设置" 标签，调整平滑因子、眼睛/嘴巴/头部影响系数。
调整显示：打开 "显示设置" 标签，调整透明度、置顶、穿透、背景等。

快捷操作

右键菜单（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,
    "center_y": 0.11,
    "scale": 1.2,
    "current_path": "..."
  },
  "device": {
    "camera_id": 0,
    "camera_width": 1280,
    "camera_height": 720,
    "camera_fps": 60
  },
  "face": {
    "engine": "MediaPipe Face Mesh",
    "precision": "高",
    "smooth_factor": 0.7,
    "eye_influence": 1.9,
    "mouth_influence": 1.0,
    "head_influence": 2.0
  },
  "display": {
    "always_on_top": true,
    "click_through": false,
    "opacity": 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 # 本文件

技术架构

技术栈架构图

┌─────────────────────────────────────────────────────┐
│ 用户界面层                                          │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐   │
│ │ 主窗口渲染器 │ │ 设置面板     │ │ 系统托盘   │   │
│ │ 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：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 社区提供的技术支持，感谢开源社区的贡献者们。