live2d-py

English README

使用 Python 直接加载和操作 Live2D 模型，不通过 Web Engine 等间接手段进行渲染。

基于 Python C Extension 对 Live2D Native SDK (C++) 进行了封装。理论上，只要配置好 OpenGL 上下文，可在 Python 中将 live2d 绘制在任何基于 OpenGL 的窗口。

代码使用示例：examples

详细使用文档：Wiki

修改和开发：CONTRIBUTING

兼容UI库

理论上兼容所有能使用 OpenGL 进行绘制的UI库： Pygame / PyQt5 / PySide2 / PySide6 / GLFW / pyopengltk/ FreeGlut / Qfluentwidgets ...

支持功能

• 加载模型：Cubism 2.1 和 Cubism 3.0 及以上版本
• 视线跟踪
• 点击交互
• 动作播放回调
• 口型同步
• 模型各部分参数控制
• 各部件透明度控制
• 精确到部件的点击检测

兼容性

Python 版本

Python 版本支持：从 live2d-py 0.3.2 开始使用 Python C Limited API，理论上兼容 Python 3.2 以上的所有版本。

Cubism Live2D 版本

live2d-py	支持的live2d模型	实现
live2d.v2	Cubism 2.1 以及更早的版本	纯 Python 实现
live2d.v3	Cubism 3.0 及以上版本	Python C Extension 封装

Python 版本及平台

✅: 可用, 支持, 已通过

❓: 尚未测试

🚧, ❌: 编译期问题或平台兼容性问题待解决

Platform	Python Version	live2d.v2	live2d.v3	构建状态	PyPI
MacOS arm64	>3.0, <=3.10	✅	❓	🚧	❌
MacOS arm64	>=3.11	✅	✅	✅	✅
Windows x86/x64	>3.0, <3.8	✅	❓	🚧	❌
Windows x86/x64	>=3.8	✅	✅	✅	✅
Ubuntu 20.04/Arch, x64	>3.0, <3.8	✅	❓	🚧	❌
Ubuntu 20.04/Arch, x64	>=3.8	✅	✅	✅	❌

注：

• live2d.v2 由 Cubism Web SDK 转写为纯 Python，尚未使用 numpy 等优化的库，性能有待提升
• Cubism 2.X 导出的模型：文件名格式常为 XXX.moc，XXX.model.json，XXX.mtn
• Cubism 3.0 及以上导出的模型：文件名格式常为 XXX.moc3，XXX.model3.json, XXX.motion3.json

使用说明

1. 在 Release 中下载对应版本的 whl 文件并安装（推荐）

pip install live2d_py-0.X.X-cpXXX-cpXXX-win32.whl

2. 通过 PyPI 安装

pip install live2d-py

3. 从源码构建，参考 安装#源码构建

示例

简易面捕

源码见 main_facial_bind_mediapipe.py

基于 live2d-py C 模块及 Qt 开发的 Live2DViewer

多模型加载

源码见 main_pygame_three_model.py

添加背景

源码见 main_pygame_background.py

模型变换 & 口型同步音频 & 点击测试

源码见 main_pygame.py

模型整体透明度示例

源码见 main_pyqt5_canvas_opacity.py

鸣谢

特别感谢以下用户为本项目提供的帮助和支持: 96bearli, Ovizro, AnyaCoder, jahtim, Honghe, RobertMeow, LUORANCHENG, TinyKiecoo, Barracuda72, GuangChen2333, makabakadot, thynetruly, mastwet, KyvYang, @Mozilla88, @CooperWang0912, @minghf85

非常感谢以下项目及其贡献者们的帮助：

CubismNativeSamples (live2d.v3)

Cubism2 Web SDK (live2d.v2)

de4js（JavaScript 反混淆工具）

JsConvert (Javascript 转 Python 工具)

D2Evil (moc 文件分析)

facial-landmarks-for-cubism （面捕参考）

Live2D 模型:

• Cubism 官方样例数据
• 雅萌工作室
• live2d-models
• 【虚拟主播模型】 宁宁vup化！