Mixer: a Blender Addon for Collaborative Editing

With Mixer, several Blender users can work together on the same data and collaborate in real time.

Disclaimer

Mixer is an open source project developed by the R&D department of Ubisoft Animation Studio. Although designed to be used in a production context it is still an experimental tool and, In spite of all our efforts to make it reliable, it may in some circumstances corrupt you Blender scenes data. Be aware that neither Ubisoft nor Ubisoft employees can be taken as responsible in such cases. Use it at your own risks.

This said, we will do our best to improve Mixer thanks to your feedback in order to provide a memorable creative collaborative experience. Have fun !

Getting started

Watch the video tutorial or dive into this step-by-step process:

• Download the Mixer zip file,

• Install Mixer as a Blender addon,

• Mind the features and pitfalls,

• Then try out your installation !

Installation

Supported versions

Mixer is developed and actively tested on Windows 10. Community users reported successful usage on Linux platform.

The currently supported Blender version is 2.93.x. Blender 3.0 will be supported soon.

Download

Open the latest release page from the Mixer Gihub releases page. Download the zip file listed in Assets that has the package icon: .

Install

Launch Blender, open the Preferences panel and go to the Add-ons section. Press the Install button located at the top of the panel. A dialog box opens, pick the Mixer zip file you previously downloaded and validate. The add-on will be installed. Click on the checkbox at the left side of its name to enable it.

Once the addon is enabled, a Mixer tab is displayed in the 3D viewport N-Panel.

Now close Blender to save your user preferences with the Mixer installation and you are ready for your first steps with Mixer.

First steps

The easiest way to test Mixer and find out what you can do with it is by using two Blender instances side by side on the same machine.

Start two Blender instances, lay them side by side. In each one, open the Mixer panel in the 3D editor.

Create a Server

On one of the Blender (say the left one), click on the Connect button.

If you are using Windows, the firewall will likely prompt you to allow access for Python.

Warning

Make sure to check Private networks and click on Allow access.

This launches a Mixer server in the background. After the server is started and Mixer is connected to the server, the panel changes.

Now click on Create Room to create a room. After the room is created, the Server rooms section of the Mixer panel displays the room name, which is Local in the picture below.

This Blender is connected to the server, which is now ready to accept a connection from a new client.

Connect to a Server

On the other Blender (say the right one), open the Mixer panel and click on the Connect button.

This connects Mixer to the server we have just setup before. The Server Rooms section lists the room name.

Warning

Joining a room wipes out your current data and replaces it with the data from the Mixer server.

Click on Join room. Both Blender are now connected to the server and their data is synchronized. Creating or moving an object in one Blender updates the object in the other Blender.

Read more about Mixer features and try by yourself.

Key Features

Overview

Mixer synchronizes in real time the modifications done to the scene and the objects it contains. During a collaboration session, Mixer displays the position of other participants and highlights their selections. See Work together for more details.

In the sections bellow we listed the features of Blender that are synchronized and those which are volontary not, as well as what is currently supported and what is not.

Warning

Undo / Redo is a important pitfall at the moment for technical as well as paradigm reasons. It is strongly adviced not to use it, it may destabilize the running collaborative session.

See Caveats for more details.

What is synchronized

Most of the elements contained in a scene, the data types, are synchronized, as well as the custom properties of all datablocks. The following table summarizes the covered features and a note indicates when synchronization is not available because the feature has not been implemented yet.

Data	Status	Comments
Action	Yes	See [Delay]
Armature	Partial	Simple rigs only. See [Armature]
Brush	No
Collection	Partial	Except collection children ordering
Camera	Yes
Curve	Partial	Except surface and Bézier curves. See [Edit], [Convert]
Grease pencil	Yes	See [GreasePencil], [Edit], [Convert]
Image	Partial	See [Image], [Media]
Keying sets	No
Library	Partial	See [Library]
Light	Yes
Light probe	No
Line style	No
Mask	No
Material	Yes	See [Nodes]
Mesh	Partial	Except split normals, custom properties, see [Edit]
Metaball	Yes	See [Edit], [Convert]
Movie clip	Yes	See [Media]
Node group	Partial	Not extensively tested, see [Nodes]
Object	Partial	Except motion paths, particles and physics. See [Convert]
Paint curve	No
Particles	No
Shape key	Yes
Scene	Yes	See [Delay]
Sound	Yes	See [Media]
Text	No
Texture	Yes
Volume	No
VSE	Partial	Except meta strips. Not extensively tested
World	Yes

Armature

Issues remain with rigs generated by Rigify.

Convert(1,2,3,4)

The result of object conversion (Object/Convert to menu) is not synchronized.

Delay(1,2)

Some updates may be delayed until another modification is detected:

• scene annotations: try to click around in the background of the 3D viewport

• animation curves names : try to toggle the curve Enable checkbox twice.

Edit(1,2,3,4)

While an object is not in Object mode (in Edit, Sculpt, Paint, …) the local modifications to this object are not sent to the other participants and the other participants modifications are not applied. Pending modifications are applied when the mode changes.

GreasePencil

• the mask layer is not correctly synchronized

• area fill is sometimes not correct

Image

Generated images and UDIMs are not synchronized. Image files are synchronized.

Library

Nested libraries will fail when shared folders are not in use. The following are not synchronized:

• the results of make local and reload

• library overrides

Media(1,2,3)

Media files are synchronized. The result of reload or media path modification are not synchronized.

Nodes(1,2)

Links synchronization sometimes fails. Some cases might cause crashes.

What is NOT synchronized

In order to provide to all participants a collaborative experience with as much freedom as they have during a solo session some features are deliberately not synchronized. This is the case for most User Interface elements, user preferences and configuration.

UI and Settings	Comments
User preferences
Key mapping
Installed add-ons
Workspace

Scene Manipulation	Comments
Object Editing Mode
Active tool	Eg: Move, Rotate, Scale…
3D cursor
Scene display mode	Show gizmos, overlays…
Viewport shading
Play mode

Scene Properties	Comments
Scene current camera	See [SceneCurrentCamera]
Render engine	See [RenderEngine]

SceneCurrentCamera

Although belonging to the scene properties, preventing the current camera to be synchronized allows each user to view and render the scene from the camera of her choice

RenderEngine

Each user can render either with Eevee, Cycle or another avaiable engine of her choice

Caveats

In addition to the limitations listed in the previous section, you should be aware of the following limitations:

Undo / Redo

Using undo may cause data desynchronisation between users, unexpected behaviors and possibly some crashes. Using undo while in Object mode may undo other participants changes. It is then strongly adviced not to use the undo feature during a collaborative session.

The undo action rises several paradigm questions such as:

• What happens in the scene when an action is undone and some work dependent on it has been done by other users, such as a mesh edit, a constraint, etc?

• What should be undone? The last action of the user doing the step backward or the last action made by any user of the session? Or all the actions of everyone up to the last action of the considered user?

• Should a redo be possible?

• …

Once the expected behavior clearly defined there is a technological challenge to face in order to address it.

Currently the undo and redo actions are “possible” as part of the default behavior of Blender. For the reasons mentioned above doing one of them can very likely, according to the context, lead to an unstable environment. It can be noticed from error messages in the terminal or more obviously from differences in terms of data in the shared scene.

At this point a synchronisation recover is unlikely and it is adviced that one of the users save the scene on her computer, everyone leaves the room and a new session is started.

In order to minimize the chances of doing an undo action we thought about blocking this feature during a session. We don’t know if this is possible and have not gone further in that direction at the moment.

File saving

The files saved by all participants are not exactly identical.

Glossary

Room

All server users that join the same room have their Blender data synchronized. A server usually hosts a single room but may host several ones in advanced setups.

Server

A Mixer server handles communication between participating Blender in order to synchronize their Blender data.

VRtist

A Virtual Reality tool for storytelling: https://github.com/ubisoft/vrtist.

Collaborating

After installing, learn how to connect with friends or colleagues on the same LAN or through Internet and work together.

Get connected

This section describes how several users can connect to the same Mixer server using a LAN or through the Internet.

Tip

It is recommended that you try Mixer locally before you attempt to connect on a network.

Whatever the network type, one user will have to create a server that the other users can connect to.

On a LAN

Host a Server

Open the Mixer panel in the 3D editor, check that the Host text box contains localhost then click on the Connect button.

If you are using Windows and starting a server for the first time, the firewall will prompt you to allow access for Python like in the image below.

Important

Make sure to allow access for private networks.

Your machine is now hosting a Mixer server and the panel changes to :

The server is now ready. Find out the IP address of your machine and communicate it to the other participants.

Connect to a Server

Start Blender and open the Mixer panel in the 3D editor.

In the Host text box, replace localhost by the IP address of the machine that hosts the server,, which is 192.168.0.48 in the example below, then click on the Connect button.

The panel now lists the room created on the server. Click on Join Room.

You are ready to collaborate with your colleagues or friends.

On the Internet

With a hosted VPN

VPN software like Hamachi, Zerotier and others can be used to execute a Mixer session over the Internet. The overall process is as follows:

• all participants:

  • download, install and start the VPN software using the VPN software instructions

• one participant:

  • creates a VPN network using the VPN software instructions

  • starts Blender, open the Mixer panel, leaving localhost in the panel Host text box, then click Connect to create a server

  • finds the VPN address of his machine and communicate it to others

• the others:

  • connect to the VPN network using the VPN software instructions

  • start Blender, open the Mixer panel and fill the Host text box with the VPN address of the server.

Hamachi

Follow this tutorial to easily install and configure an Hamachi server:

If the connection to the server fails, see the networking FAQ.

Other VPN software

Mixer has been reported to work successfully with other VPN software:

• Zerotier

• OpenVPN and portmap.io .

With port forwarding

Collaborating over the Internet without a VPN may require to setup port forwarding and is more involved.

On the network that hosts the server

The user who creates the server must setup a TCP port forwarding rule on his router:

• on the machine that hosts the server:

  • setup and start a Mixer server. Keep localhost as the value in the Host text box.

  • find the IP address of the machine that hosts the server, say 192.168.0.10

• on the router:

  • find the public IP v4 address of the router using the router administration tool or http://whatismyip.host/. You will need to share this address with other participants Say you found the public IP v4 address of your router is 203.0.113.17

  • setup a TCP port forwarding rule to the machine that hosts the server (192.168.0.10 in our example), and the TCP port used by Mixer (12800 by default).

  • check or edit the value of the public forwarded port:

    • If the public forwarded port can be set to 12800, use this value. This setup creates a TCP port forwarding rule from 203.0.113.17:12800 to 192.168.0.10:12800.

    • If the public forwarded port cannot be set to 12800, configure it to a permitted value, say 9090. This setup creates a TCP port forwarding rule from 203.0.113.17:9090 to 192.168.0.10:12800

On the other users locations

Start Blender and open the Mixer panel in the 3D editor.

• In the Host text box, replace localhost by the public address of the router on the server location, (203.0.113.17 in our example).

• If the public forwarded port is not 12800:

  • Open the Mixer preferences using the Mixer panel title bar setings icon

  

  • in the Port text box type the public forwarded port number, 9090 in our example

  

  • close the preferences windows

• in the Mixer panel, click on the Connect button.

You are ready to collaborate with your colleagues or friends.

Work Together

After you are connected to a Mixer server, you can create or join a room in order to collaborate with other users. The instructions of this section apply to any type of network connection.

Create a room

Warning

All the other users must use the same version of Blender and Mixer as the room creator.

To create a room after you are connected to a server, type a name in the Room text box (Local in the picture below), then click on Create room.

Note

Creating a room uploads the the contents of your current Blender data to the server, which can take up to several minutes.

After the data has been uploaded, the Mixer panel lists the room in the Server Rooms list and others can join the room.

Join a room

Anyone connected to a Mixer server can join a room as long as the user runs the same Blender and Mixer versions than the room creator.

Warning

When you join a room, your current Blender data is cleared without notice and replaced by the room contents.

Joining the room will download the room contents and this process may take up to several minutes if the room is large or the network is slow.

Work together

While you are joined to a room, your Blender updates are sent to the other users and your Blender is updated with the changes received from the other users.

The updates are sent and received in real time with a few exceptions. When an object is not in Object mode (for instance a Mesh is in Edit or Paint mode), the updates to this object are not sent to the other users and the updates received from other users are not processed. All the updates will be sent or processed as soon as the object mode changes. There are some other cases when updates may be delayed, that are listed in update delays.

Some items are not synchronized, such as the 3D cursor, the current frame time, as well as other UI-related data.

Tip

Read about the caveats and save your work regularly during the session.

Leave a room

When you leave a room by clicking on Leave Room in the Mixer panel, your Blender data is no more synchronized with the other room users.

If you want to join the room again later, your local data will be cleared and the room contents will be downloaded again into your Blender instance.

Warning

When the last room users leaves the room, the room is destroyed unless Keep Open is checked in the room properties.

Advanced usage

In case you keep a server running without tying it to a Blender instance, you can also start a standalone server.

Starting a Standalone Server

The Mixer server is usually started by the addon when the user clicks on the Connect button. This ties the server to a machine with Blender installed and requires that Blender remains up on the machine that started the server.

Using a standalone server allows you to run a server on a machine without Blender running or even installed. The server machine may use a different operating system than the clients.

Warning

Make sure to use the same Mixer version on the server and on the clients.

This has only been tested with Python 3.7.4

To start a standalone server:

• download the Mixer zip file as described in the download section

• unpack the zip file

• start a command prompt

• change directory to the directory that contains the mixer directory

• execute the command to start a server:

  python.exe -m mixer.broadcaster.apps.server --log-level INFO
  

Find the IP address of the machine that executes the server and communicate it to all the participants.

All the participants connect to the server, one of them creates a room and the others join the room.

Frequently asked questions

General

Can I control access to the server or a room?

No. Anyone who knows the address a Mixer server and has network access to the server can join a room an collaborate.

Can I control access to parts os a scene?

No. All room users can edit all the Blender data without restriction. If two users edit simultaneously the very same elements data corruption will occur.

Will files saved by all participants contain the same data?

Not exactly. Here is a non limiting list of situations that will cause Blender files saved by participants to differ:

• Creating or updating data that is not synchronized: see the list of synchronized data

• Simultaneous modifications of the same data by several users.

• Usage of media files: file paths will be different unless shared folders with the same base folder are used.

• Extreme network latency

How does Mixer handle simultaneous and conflicting modifications?

Mixer handles these simultaneous and conflicting modifications:

• simultaneously creating objects with the same name

• renaming datablocks with different names

• linking different objects to the same collection

The following conflicting modifications are not handled, and in these cases, the participants will end up with different attribute values:

• setting an attribute with different values.

• adding or removing array elements, like in object modifier or grease pencil layers

How many users can collaborate in a session?

There is no hardcoded or configurable limit to the number of users that can collaborate. The limit will come from the response times that depend on the number of users, scene complexity and network performance.

Can I have a server running without executing Blender?

Yes. See Starting a Standalone Server.

Why is room join sometimes so long?

The server room records all modifications performed by all participants and does not store the current Blender state. A new user who joins the room receives all the modifications since the room creation.

Networking

Why does Connect fail with a timeout error?

The machine with the address listed in the Host text box cannot be reached for one of the following reasons:

• the address is misspelled

• the machine is not up or the server is not started

• the machine cannot be reached because of a network configuration error. See the documentations for connecting in a LAN or over the Internet.

How can I fix a Hamachi connection failure?

The Hamachi setup may have configured your Hamachi network in public mode instead of private. An Hamachi community discussion explains how to change to private network.

How do I find the IP address my machine?

The procedure depends on the operating system.

On Windows you can open a command prompt, then execute the IPCONFIG command. The IP addresses of your machine are listed in the lines labeled IPv4 Address

Failures and errors

Why is the “Join Room” button grayed out?

The Join Room button may be grayed out because your Blender version and/or Mixer version does not match the Blender and Mixer version of the user who created the room. By default, all users must use the exact same version of Blender and Mixer.

Why does my update fail to appear on other participant Blender?

Check the following :

• are you and the other participants actually connected to the server? When you are connected, the Mixer panel should display the Disconnect button in blue.

• are you attempting to synchronize data that is not or partially supported? See the list of synchronized data and their restrictions.

If you think you have found a bug, please report an issue.

Other users seem not to have the same scene content than I do

During a session it may appear that one or more participants mention they don’t see the same things as you do. This usually appends because of one of these reasons:

• a participant used a feature of Blender that is not yet covered by Mixer. See Features

• a participant called an undo action. See Caveats - Undo / Redo

• or there is a bug that went through our quality check process. Please repport it using these guidelines: Report an issue.

Feedback and Issues

Feedback

For feedback, suggestions and to discuss ideas around Mixer you can directly contact us on Blender Chat: https://blender.chat/channel/mixer-addon

Reporting an issue

Before reporting an issue, please make sure that are using the latest version and check :

• the faq,

• restrictions in What is synchronized ,

• known problems in Caveats,

• current GitHub issue list .

If you think you have found a bug or would like to propose a new feature, please report an issue on Gitlab.

Please consider attaching the Mixer log file:

• open the Mixer preferences using the Mixer panel title bar settings icon

• in the preferences window, go to the Connection Settings group and click on Open Log Folder.

• attach the relevant file to the issue.

On YouTube

Many thanks to community members who published YouTube videos about Mixer.

May 2021

• askNK: Blender Mixer Released! - Multi-User Addon -Walkthrough & Lessons!

• Gamefromscratch: UBISOFT Mixer for Blender Released! Blender now has Multiplayer Support!

• JuanyBabas: Ubisoft Mixer para Blender, trabaja en línea, colabora con el mundo

October 2020

• Brainy Man: МУЛЬТИПЛЕЕР В BLENDER | Аддон Mixer от Ubisoft

September 2020

• Oby 1: 2 Player Chaos on Blender

• Landetty: Mixer add-on Quick Set Up for WORLDWIDE use!

August 2020

• Curtis Holt: Ubisoft Releases Mixer, HardOps Overview and More!

• Hinting Blender: Addon - mixer - Collaborative work using Blender (English)