基于 Python 的 Live2D 虚拟主播软件

设置面板

• 模型设置 - 加载自定义 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 可用空间（包含模型文件）

快速开始

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

1. 克隆或下载项目

   git clone https://github.com/yourusername/bbb-live2d-py-v4.git
   cd bbb-live2d-py-v4
   

2. 创建 Conda 环境

   conda create -n live2d-mascot python=3.10
   conda activate live2d-mascot
   

3. 安装依赖

   pip install -r examples/requirements.txt
   

4. 运行程序
   • 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 安装

1. 安装 Python：访问 python.org 下载 Python 3.10+ Windows installer，安装时勾选 "Add Python to PATH"。
2. 安装 Git（可选）：访问 git-scm.com 下载并安装 Git。
3. 安装 Conda（推荐）：下载 Miniconda 或 Anaconda 并运行安装程序。
4. 克隆项目并安装依赖：

   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
   

5. 运行程序：python main.py

macOS 安装

1. 安装 Homebrew（如果未安装）：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. 安装 Python 和 Conda：

   brew install [email protected]
   brew install --cask miniconda
   

3. 克隆项目并安装依赖：

   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
   

4. 运行程序：python main.py

Linux 安装

1. 安装系统依赖
   • 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
     

2. 克隆项目并安装依赖：

   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
   

3. 运行程序：python main.py

使用指南

基本操作

1. 启动程序：运行 python main.py 或双击 run.bat（Windows）。程序启动后会显示 Live2D 角色窗口。
2. 面部捕捉：程序会自动打开默认摄像头。面向摄像头，保持适当距离（50-100cm），确保面部光线充足。
3. 打开设置：
   • 方法 1: 右键点击 Live2D 窗口 → 选择 "设置"
   • 方法 2: 右键点击系统托盘图标 → 选择 "设置"
4. 加载模型：打开设置面板 → "模型设置" 标签 → 点击 "浏览" 按钮选择 Live2D 模型文件（.model3.json 或 .model.json）。模型会立即加载并显示。
5. 调整模型：
   • 位置: 调整 "中心 X" 和 "中心 Y" 滑块
   • 大小: 调整 "缩放" 滑块
   • 画布: 调整 "画布宽度" 和 "画布高度"
6. 调整捕捉参数：打开 "设备设置" 标签，调整平滑因子、眼睛/嘴巴/头部影响系数。
7. 调整显示：打开 "显示设置" 标签，调整透明度、置顶、穿透、背景等。

快捷操作

• 右键菜单（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 对话集成
• 云端模型库
• 移动端远程控制

贡献指南

欢迎任何形式的贡献！

如何贡献

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 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 社区提供的技术支持，感谢开源社区的贡献者们。