python-mvr
Python library for MVR (My Virtual Rig). MVR is part of GDTF (General Device Type Format)
MVR specification as per https://gdtf.eu/mvr/prologue/introduction/
See source code for documentation. Naming conventions, in general, are identical to that on the GDTF, CamelCase is replaced with underscore_delimiters.
This library is used for example by BlenderDMX (BlenderDMX on GitHub).
Status
- Reading and Writing of most aspects of MVR 1.6 (DIN SPEC 15801:2023-12) should be covered.
- MVR-xchange is not implemented in this library but full Python implementation exists in BlenderDMX and potentially could be moved here.
Installation
- With uv:
uv add pymvr
- With pip
pip install pymvr
Usage
Reading MVR
import pymvr
mvr_file = pymvr.GeneralSceneDescription("mvr_file.mvr")
for layer_index, layer in enumerate(mvr_file.scene.layers):
... #process data
Writing MVR
Validation notes
- Each object now enforces required children/fields when writing. Missing mandatory data will raise
ValueError.- For convenience, fixtures/truss/support/video/projector auto-fill missing IDs with minimal defaults (
FixtureID="0",FixtureIDNumeric=0) when not a multipatch child.Addressesuses plural fieldsaddresses/networksto align with the spec’s container semantics.- Required nodes such as
Geometries,SourceinsideMappingDefinition/Projection, andProjectionsonProjectormust be present; emptySources/Projectionswill raise.
Load and Export an MVR
import pymvr
from pathlib import Path
# 1. Read MVR file
mvr_read = pymvr.GeneralSceneDescription("mvr_file.mvr")
# 2. Create a writer instance
mvr_writer = pymvr.GeneralSceneDescriptionWriter()
# 3. Serialize the scene object into the writer's XML root
mvr_writer.serialize_scene(mvr_read.scene)
# 4. Serialize the user_data object into the writer's XML root
mvr_writer.serialize_user_data(mvr_read.user_data)
# 5. Add necesarry files like GDTF fixtures, trusses, 3D objects and so on
# Skipped in this example
# 6. Write the MVR file
output_path = Path("exported_mvr_file.mvr")
mvr_writer.write_mvr(output_path)
Creating a new MVR
import pymvr
from pathlib import Path
# 1. Create a writer instance
mvr_writer = pymvr.GeneralSceneDescriptionWriter()
# 2. Build the MVR object tree
# Create a scene object
scene_obj = pymvr.Scene()
# Create layers and add them to the scene
layers = pymvr.Layers()
scene_obj.layers = layers
# Create a layer and add it to the layers
layer = pymvr.Layer(name="Test layer")
layers.append(layer)
# Create a child list for the layer
child_list = pymvr.ChildList()
layer.child_list = child_list
# Create a fixture and add it to the child list
# Note: A valid fixture would require more attributes
fixture = pymvr.Fixture(name="Test Fixture")
child_list.fixtures.append(fixture)
# 3. Serialize the scene object into the writer's XML root
mvr_writer.serialize_scene(scene_obj)
# 4. Add any necessary files (like GDTF fixtures, trusses...) to the MVR archive
# The list should contain tuples of (file_path, GDTF_file_name)
files_to_pack = []
if fixture.gdtf_spec:
files_to_pack.append((fixture.gdtf_spec, fixture.gdtf_spec))
mvr_writer.files_list = list(set(files_to_pack))
# 5. Write the MVR file
output_path = Path("exported_mvr_file.mvr")
mvr_writer.write_mvr(output_path)
See BlenderDMX and tests for reference implementation and usage examples.
Changelog
See CHANGELOG for details.
Development
PRs appreciated. You can use uv to get the project setup by running:
uv sync
Format
- To format, use ruff
uv run ruff format pymvr/*
Pre-commit hooks
- You can use the pre-commit hooks
uv run pre-commit install
Testing
- To test, use pytest
uv run pytest
- To test typing with mypy use:
uv run pytest --mypy -m mypy pymvr/*py
Citation
If you use this library in your research, publication, or software project, please cite it as follows:
@software{pymvr2025,
title = {pyMVR: Python Library for My Virtual Rig},
author = {{OpenStage}},
year = {2025},
version = {1.0.6},
url = {https://github.com/open-stage/python-mvr}
}
Metadata
Release files for pymvr 1.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pymvr-1.0.7-py3-none-any.whl | Python 3 | none | any | Details for pymvr-1.0.7-py3-none-any.whl |
Release files / pymvr-1.0.7-py3-none-any.whl
| Download URL | pymvr-1.0.7-py3-none-any.whl |
|---|---|
| Size | 15.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1387c17971b3ed59f1e1284cdeea20f189d93e94f7a8da1b5a3617c5f024a1fb
|
|
BLAKE2b-256 checksum How to use checksums |
12438e5ab72d8ba792f719463b888c1fc20fd5cb8bfdd2d067c55b1e0a9b506f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":null,"id":"forky","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for pymvr 1.0.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.