AddRoutes

Important

If you upgrade from M.O.M, make sure you uninstall it before installing AddRoutes. 
Don't worry if you have some errors while disabling M.O.M. 
Save the preferences, restart Blender, then enable AddRoutes.

Introduction

MIDI/OSC and More has been renamed as AddRoutes in March 2020 ! 

AddRoutes is a new Add-on for Blender 2.8 gathering AddMIDI and AddOSC in the same package. As a novelty an application for smartphones and tablets (Blemote) is currently developed to ease the remote control of Blender.

Download

For the last release "ready to go" (Windows, OSX, and Linux), here is the LINK.     

Disclaimer: By downloading this software you understand that AddRoutes is still under development and that some problems might occur during its use.

For installation, like any Add-ons, don't unzip and do "Install From file", then look in the category "System" to enable it.

The Add-on is now located in the "N panel", at the right, and has 2 tabs (AddR Config and Routes).

License and Status

AddRoutes inherits from the Blender license which is the GNU GPL license (like all Blender Add-ons). 

Development and maintenance of this Add-on has been a lot of work. If you can, please support financially this project.

Even though the Add-on can already be useful, it needs some polishing and new handy features and improvements can be wished. Please share your thoughts. 

A thread on BlenderArtists can be found here.  

If you are a developper sources can be found on github: https://github.com/JPfeP/AddRoutes.

General Principle

A route is the basic element to connect an external source, a remote physical device or software, to a blender property. You can create several routes and organize them as categories. 

Each route has 3 sections:

  1. Property (Normal/Multi/Python)
  2. Engine (Please see the related pages : MIDI / OSC / Blemote)
  3. Action (Keyframe options and IN/OUT mode)

Here is an example:

And, as we will see later there are 2 kinds of routes (Project routes and System routes). 

1) Property

There is 3 ways in AddRoutes to target a property:

  1. By picking an ID-block, an item, and by filling a path to the final property. 
  2. By using the Multi routing feature which allows to target several objects with the same property or the same object with several similar sub-elements (like bones or shapekeys).
  3. By using the Python option, which allows to dynamically set the whole path of the property.

The 2 first types are the fastest as some precalculations are made while configuring the route. The third makes a Python evaluation when a route receives or sends, which can be slower.  

Let see first some common settings for a blender property which relates to the first type:

  • ID-block: In the Blender philosophy each object belongs to a category (mesh objects, curves, materials, textures). When you edit manually a route, the first thing is to use the drop-down menu to choose the right category. In the example below the user is using "Key" (which is for shapekeys) :  
  • Item: Once the right ID-block is used, you have to select one of its members. Pick one in the drop-down list, or use the search feature by typing a few characters.
  • Path: This represents the path toward the final property you want to control. Please see the paragraph "Things to know" below about the particular cases you might encounter.
  • Array Index: Some engines cannot address directly arrays and requires an index to target the proper sub value (x/y/z or r/g/b/a for instance) 
  • All: This check box is for the engines that can deal with a whole array.
  • Deg<->Rad: This checkbox appears when the property is an angle, and will convert for you a degree value into radians (Blender internal preference thru the python API).   

Easy adding

Because manually editing each route Path can be tedious, there is a new entry in the contextual menu to automatically do that. When the mouse cursor is over a targeted property in its related panel, invoke the menu with the right button and choose "Create realtime route". A new route will then appear in the list with the proper parameters. 

Red Alert !

Note: If a route from the type 1 or 2 is "non functional" and you try to set it for real use, its fields will appear in red, until you fix the issue. This won't happen however with Python route (type 3) because the fault will reveal itself only when receiving. You can use however the Debug options to be informed if there is any trouble. 

More about Multi routes

We have seen basically the first way to define a property but some engines (MIDI or OSC) can actually deal with complex data. This is needed for instance to represent visually a piano keyboard when chords are played or when using the Add-on with a motion capture software. Please see the MIDi and OSC pages for more details. 

For now Blemote cannot deal with multi routes.

Python routes

This is a recent addition in AddRoutes. The secret intent is to be able to use the context dependant properties that the Blender API offers (like bpy.context.object.location for instance).

Theses routes are as well the only one available when defining System Routes that we will see later.

It's not possible currently to mix Multi routes and Python routes.

 

As you see the ID-Block, Item and Path fields have been replaced by theses simple options:

  • To eval: This is the python string you want to pass to eval(). C and D are shortcuts for bpy.context and bpy.data
  • Context: Unfortunatly invoking bpy.context most of the time requires a specific context. The default string allows to access objects in the 3D scenes. This might not suit in every cases and require a different string. This is not needed for bpy.data however.
  • Is Array (use index): Normally the Add-on detects automatically if a property is an array. But as the python evaluation can change dynamically, you need to explicitly check "Is Array" to be able to specify as well an index as a complement or use "All" to deal with a whole array (if OSC is used as engine).
  • Is Angle: Normally the Add-on detects automatically if a property is an angle and offers the complementary option Deg<->Rad. You have now to select this option manually first.


2) Engine

Currently 3 choices are offered (MIDI/OSC/Blemote). Once you select one you will see specific options to configurate further the route. Please see the dedicated pages to learn more about them. 

When you select MIDI or OSC, you will see a 'Blemote' checkbox at the right of the drop-down menu. This is an extra option to force such a route to display a slider in Blemote for quick testing. 

3) Action

In this last section there are in turn 3(+1) sub-sections:

  • Actualization : Replace or Expression.The default mode is "Replace" which just sets the Blender property with the incoming value. The second mode "Expression" invokes basically a python eval() function where 2 reserved keywords are available: IN and PROP. IN is the incoming value, PROP is the current blender property value. You can use Numpy with the "np" prefix like that: np.log(IN). Note that for an angle, IN reflects the result converted in radians if you use the feature "Deg<->Rad", but Blender still expects your expression to return a result in radians. The conversion stage is before this python evaluation.  
  • Keyframe options: Theses appear only when Rec is enabled.

  • Enveloppe settings: Intended for MIDIfile conversion, it can in fact serves for OSC as well. However it's based on the succession of positive and null values and won't work well without that. See the MIDI chapter for more.

  • Receive/Send/Both/Off and Rec: Should be relativly easy to grasp. However please note that sending is currently active only when Blender is playing the animation. The second condition is that the property value has changed. 

Project Routes and System Routes

If it's true that project routes can use the 3 methods to target properties, and are saved with the project blend file, system routes however are saved with the Add-on preferences settings and the Add-on can't reference the scene objects.

Therefore system routes can only use the Python method. System routes are always available as soon as Blender starts and remain when you load any project. But you need need to save the preferences globally to find them back when you restart Blender. A short cut has been provided in the Routes Panel.

System routes are mostly intended to control the user interface whereas project routes are to address scenes properties. 

However it's a general rule and if a python route fails to find a scene object, it won't produce any blocking error. 

For now only Blemote which has settings stored in the Add-on preferences can be ready as soon as Blender starts. In the future, OSC and MIDI engines will have a default configuration as well (with the option to be overriden by the blend project settings). 

Tools

This new panel will probably grow in the future to offer a few facilities. You can now:

  • Set the focus on a category with the drop-down list. 
  • Create a new category with the "+" icon
  • Remove a category with the "x" icon (the "contained" routes are not deleted but re-affected to 'Default')
  • Rename a category (select it first with the drop down menu)
  • Copy a category and its routes to a different scene (idem) 

Routes sorting if set to "Category" will display only the routes belonging to it. This option will serve in Blemote as well to organize your sliders. 

System routes belong to their own category 'System' and this cannot be changed (for now). 

The options in the "Extra route parameters" section allow to show/hide some recent new parameters, in order to help readability of the routes settings and keep the presentation simple. The route category is hidden by default. 

Overflows events: The number represents the times an engine has not been to process all the elements in the stack during its cycle of execution.    

Add-on Settings

In the Blender Preferences Panel search for AddRoutes:

  • Refresh rate of engine (ms): The default value (1ms) might be unecessary low as it will be usefull only for 1000 FPS animation. 
  • Maximum events per cycle: As well adjust to your taste. If the limit is reached, the stack is cleaned and the overrun counter incremented (displayed in the Tools Panel).  

The Blemote options are explained in the Blemote page.

About Recording

Please be cautious with the "rec" button. It relies on the "is_playing" flag that Blender turns "on" and "off" when you play the current animation OR when you move the playhead manually. 

You might be better off to disable "rec" on a route just after the recording to avoid unwanted keyframe insertions while you move the playhead inadvertently.

You don't need to enable the auto-keying button in the Timeline, it's a different feature.  

Workflow

It's a very personal subject, but if I could share a few hints, I would advise to work as much as possible in realtime without using much keyframing. The "revolutionary" aspect of this add-on is, for the first time in history, to be able to work both on music and 3D visuals at the same time, under some very good conditions. EEVEE is a blessing and a strong opportunity for a new kind of creators who would want to push the art of videoclips way beyond its current state. Computers are fast, storage and RAM are cheap, it's time to invest in some new hardware and be the first to seize this opportunity. 

These new conditions will still imply nonetheless to have a reflection about means in art. You might still have to prevent yourself from using too heavy objects or scenes to keep the frame rate steady. Art is about emotion not technics, and time is the matter.  

Then you might want to produce a first final video, things might get less clear at this point, as several strategies might lead to the final product. 

To get a very predictable result, and tight sync'ing, exporting to a midifile (or to a textfile in the case of OSC, later) is probably the best option. For MIDI data, converting notes to keyframes is probably avoidable. A limit could be you need more than 16 tracks. I would then advise to convert only monophonic channels or to break the project into several midifiles. 

On this subject, it might be a good idea, specially with a project that lasts more than a simple video clip to break each part into several midifiles and may be into several D.A.W. files as well. Blender would render each sequence as frames that in turn you would gather into a final video project (either using the Blender VSE or another application) 

Things to know

  • Don't use "location.x" or "location[0]" when you set a data-path manually but "location", then set the index that will appear. Same for any property being an array (like colors). 
  • Frame dropping as sync method might produce incoherent results while making a midifile contribute during playing
  • Using a animation step > 1 is not supported for midifile contributing, but shouldn't be a pbm for converting. 
  • MIDI CC's 98 and 100 are reserved for RPN/NRPN and cannot be used currently (might change later) as simple 7bit continuous controllers. 
  • Angles are expressed in radian internally thru the Python API by Blender (and therefore the add-on complies), and not in degree like in the interface. 360° = 2*pi. The Add-on however offers an option for conversion (done in python).
  • Using drivers is fast (no python calculation) and offers nice added features. Instead of targeting directly an object property, you can create an empty object and use its axis location X, Y, Z as the support for the information you want to inject in Blender. Then, with a driver you can control even more the information and shape it with curve to control the object you really want to animate.
  • You can enable both "Tooltips" and "Python Tooltips" in Preferences/Interface/Display to have information about the path of a property when the mouse hover on it. This helps a lot to solve some problems while setting routes manually.
  • Blender sometimes uses "bridges" internally to describe the path of a property (called as nested properties in the documentation). For clarity, you might want to select the proper category "Key" (for shapekeys) instead of using "Object" then have a bridge (like "data") in the path. For instance, these 2 properties are the same: bpy.data.objects['head'].data.shape_keys.key_blocks['eyeBlink_L'].value  bpy.data.shape_keys['Key'].key_blocks['eyeBlink_L'].value
  • Another oddity is that historically the Node System was only for material shaders then it was generalized to be used for many usages. However, Blender keeps a special treatment for material shaders, when you enable the nodal system, you won't find your material available in the Nodes category. Therefore the add-on has special code to handle this frequent exception.      

Credits

This Add-on relies on a few libraries: