vrmkit

English | 日本語

.vrm（VRM アバター）のメタ情報・表情・スプリングボーンを読み取る純 Python ライブラリ。

概要

VRM ファイルは中身が glTF（GLB）なので、メタ情報を取り出すだけでも普通は Unity(UniVRM) や Blender が要ります。vrmkit は Unity を起動せず、サーバー / CI / バッチから 「このアバターは商用利用 OK か」「どんな表情が入っているか」を機械的に調べられる、 pip で入る読み取り専用ライブラリです。VRM 0.x と 1.0 の両方に対応します。

特徴

• 標準ライブラリだけで動く（実行時の追加依存なし）。.vrm を GLB として直接読む。
• VRM 0.x / 1.0 を自動判別し、同じ API で扱える。
• 作者・利用許諾・表情・スプリングボーンを型付き dataclass で取得（py.typed 同梱）。
• 読み取り専用。アバターを書き換えない。

インストール

pip install git+https://github.com/kyo5uke/vrmkit-py

使い方

import vrmkit

v = vrmkit.read_vrm("avatar.vrm")

print(v.spec_version)               # "1.0" または "0.0"
print(v.meta.name, v.meta.authors)
print(v.meta.allow_commercial_use)  # True / False / None
print(v.meta.avatar_permission)     # "everyone" / "only_author" など

for e in v.expressions:
    print(e.name, e.preset, e.is_custom)

for s in v.spring_bones:
    print(s.name, s.joint_count)

バイト列から直接読むなら vrmkit.parse_vrm(data)。元の glTF JSON は v.gltf、 生の meta 辞書は v.meta.raw から取れます。

主な meta フィールド

フィールド	意味
name / authors / version	名前・作者・バージョン
avatar_permission	利用できる人（only_author / explicitly_licensed_person / everyone）
allow_commercial_use	商用利用の可否（True / False / None）
allow_violent_usage / allow_sexual_usage	暴力・性的表現の許可
allow_redistribution / modification	再配布・改変の可否
license_url / license_name / other_license_url	ライセンス
raw	元の meta 辞書（モデル化していない項目はここから）

注意

• 許諾フィールドは 0.x / 1.0 を best-effort で正規化しています。法的に厳密な判断は meta.license_url や meta.raw を確認してください。
• 現状は meta・表情・スプリングボーンの読み取りに対応。Humanoid ボーンや マテリアル（MToon）は未対応です。

ライセンス

MIT