How emuman/blender-midi-utils works
Main Components
• Blender Integration Layer – This layer manages how the addon behavior is triggered from within Blender. It includes integration with Blender’s UI (adding a panel under the “MIDI Utils” tab in the 3D viewport) and handling the user inputs for MIDI file selection, track selection, keyframe parameters, and keyboard creation.
• Core Processing Module – This component contains the core logic for converting MIDI messages into positional/rotational keyframes. Functions in this layer extract MIDI data (using the Mido library, as required by the README) and apply interpolation (attack time, release time, anticipation, etc.) to generate Blender keyframes.
• Utility Functions – This refers to the helper functions (located in utils.py) and any property definitions (properties.py) that support the conversion processes and the creation/management of keys for the virtual keyboard.
• Data Management – This includes the handling of keyboard collections and empties (Blender objects following a naming convention) that store positional data for keys. It involves parsing names (e.g., "CollectionName_note") and managing defaults when keys are missing.
• Configuration and Initialization – The __init__.py file is used to register the addon with Blender and to set up the integration points (panels, menus, context menus).
Relationships and Interactions
• The Blender Integration Layer (UI panel) serves as the frontend. When a user interacts with the panel (e.g., clicks “Create Keyframes” or “Create Keyboard”), events are triggered that call functions from the Core Processing Module.
• The Core Processing Module uses Utility Functions (from utils.py and properties.py) to process the input parameters, read the specified MIDI file, and calculate the keyframes.
• The Data Management component interacts with the Core Processing Module when it needs to read/write the positions of keys from the designated keyboard collections.
• Initialization (via __init__.py) sets up the addon and registers all of these components with Blender so that the integration layer appears in the UI.
Architectural Patterns and Key Design Principles
• Separation of Concerns – The project divides responsibilities between user interface, core processing, and utility/helper functions.
• Modularity – With a small file tree, each file focuses on a specific role (e.g., properties, utilities, initialization).
• Loose Coupling – The UI layer triggers core functionality without embedding business logic, making it easier to extend or modify each part individually.
• Clear Data Flow – Inputs from the Blender panel are processed by the core logic which then drives changes in the Blender animation (keyframes and object positions).
Relevant Technologies, Frameworks, or Libraries
• Blender Python API – For creating the UI panel, registering the addon, and interacting with the 3D viewport.
• Mido – A third-party Python library used for handling MIDI file processing.
• Python – The language used to implement and integrate these functionalities.
• User Interface Panel (Blender “MIDI Utils” panel)
• Event Handlers / Operators (triggered by UI actions)
• Core MIDI Processing Module (processing MIDI files and converting messages)
• Utility Functions and Properties (helper methods for calculations and handling configuration)
• Data Management (handling keyboard collections and empties)
• Blender API Interface (shows interplay with Blender’s registration and keyframe system)
• Flow from the UI Panel to the event handlers.
• Use rectangles for modules/components.
Final Recommendations
• Do not oversimplify; aim to represent every role from the UI input, through data processing, to the final integration with Blender’s animation system.
• Python module (properties.py, utils.py, __init__.py) is represented according to its function.
• Integration with external libraries (Mido) and how the addon relies on Blender’s built-in event system.