Repository navigation
Home
Arkueid edited this page Sep 29, 2026
·
14 revisions
本 Wiki 编辑权限对所有人开放,欢迎大家前来编写修改使用说明、分享使用技巧、更多玩法~
English version: Home.en
live2d-py 是一个 Python C Extension 实现的 Live2D 库。
live2d-py 使用 CMake 构建项目,主要模块包括:OpenGL API 管理库 Glad、 Cubism Live2D 官方发布的 Core 和 Native Framework,基于官方 Sample 魔改的 Main 模块,以及 Python 对前三者的封装 Wrapper 模块。
本项目的主要目的是为 Python 提供 Live2D 渲染功能。
此外,也可将本项目中 Python 封装的部分剔除,在仅使用其 C 模块(Core、Framework、Main)的基础上进行二次开发,编写基于 C/C++ 的 Live2D 应用或者为其他编程语言(如 alive2d)写 C 绑定库,提供 Live2D 渲染功能。
live2d模块只为单线程使用设计,请勿在多个线程中操作live2d.Model
自 1.0.0 起,Cubism 2.1 与 Cubism 3.0(含 4.0)模型由同一个类 live2d.Model 加载,加载时根据模型 json 自动识别版本:
import live2d
live2d.init()
model = live2d.Model()
model.LoadModelJson("path/to/model3.json") # Cubism 3.0+ 模型(.model3.json)
# 或
model.LoadModelJson("path/to/model.json") # Cubism 2.1 模型(.model.json)
print(model.Version()) # 3 或 2
print(model.IsV3()) # True / False- Cubism 2.1 模型由 C++ 移植(v2cpp)实现,性能远优于纯 Python 版本
- 纯 Python 的
live2d.v2已废弃(导入时打印提示),请改用live2d.Model - 完整接口提示见 package/live2d/_live2d.pyi
具体与图形库结合的用例示例见 examples 文件夹。
✅: 可用, 支持, 已通过
❓: 尚未测试
🚧, ❌: 编译期问题或平台兼容性问题待解决
| Platform | Python Version | live2d.Model |
构建状态 | PyPI |
|---|---|---|---|---|
| MacOS arm64 | >=3.11 |
✅ | ✅ | ✅ |
| Windows x64 | >=3.11 |
✅ | ✅ | ✅ |
| Ubuntu/Arch Linux, x64 | >=3.11 |
✅ | ✅ | ✅ |
注:
- Python 版本要求
>=3.11 - Cubism 2.X 导出的模型:文件名格式常为
XXX.moc,XXX.model.json,XXX.mtn - Cubism 3.0 及以上导出的模型:文件名格式常为
XXX.moc3,XXX.model3.json,XXX.motion3.json - 本仓库包含 Cubism Core 及 Framework(位于
Live2D/),无需自行下载 SDK