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).

GitHub Page, PyPi Page

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

Latest development version (if exists on pypi.org)

uv add pymvr --pre

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

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
scene_obj.to_xml(parent=mvr_writer.xml_root)

# 4. Add any necessary files (like GDTF) to the MVR archive
# (This example fixture doesn't have a GDTF file, so this list will be empty)
files_to_pack = []
if fixture.gdtf_spec:
    # The list should contain tuples of (source_path, archive_name)
    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("example.mvr")
mvr_writer.write_mvr(output_path)

print(f"MVR file written to {output_path.resolve()}")

Exporting loaded 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_read.scene.to_xml(parent=mvr_writer.xml_root)

# 4. Add necesarry files if needed
# Skipped in this example

# 5. Write the MVR file
output_path = Path("example.mvr")
mvr_writer.write_mvr(output_path)

print(f"MVR file written to {output_path.resolve()}")

See BlenderDMX and tests for reference implementation and usage examples.

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