SpeechBot – A handy script to load and save morpher keys

Jun 20, 2011 by     3 Comments    Posted under: 3dsMax


Yakkety Yak, It is always said that careless talk can cost lives, but careless talk in production costs you time. Perhaps that is why they call them deadlines.

For many years, I have used the same system to deal with lipsync within production, and it is with great pleasure that I release it to the community now. This script is called Speechbot, and will take a character that uses a morph modifier for lipsync and save the data to XML. This can then be re-applied at a later stage.

My approach for years and many productions has been to lipsync everything before you begin animation (which is hardly ground breaking), but it does make most sense to do this first as it doesn’t interrupt the animation workflow. Over the years, this has worked well with all sizes of productions as you can assign the lipsync to junior animators who want to get an idea of the production before jumping in at the deep end. It also allows you to standardise the output as the people doing it become more familiar with the characters and you don’t get individual animators doing their scenes differently. Generally the lipsync at this stage is to provide the sense of the speech phonemes/visemes and not necessarily the facial performance so the artist is still free to adjust the keys and push the expressions further when they animate to the scene audio.

Being able to save the files to XML has helped on the larger productions too, as we have been able to outsource the lipsync to another animation company who only need to email their work to us at the end of each episode in the form of small XML data files. This is the only thing we have to worry about synchronising. We also worked with two other external companies who were doing animation. Again, they could be emailed the lipsync for their scenes and everything was cohesive and organised.

Why don’t you just use max’s Load/Save animation?

That’s a simple one – excluding the fact that load/save animaition is barely scriptable, it just doesn’t work reliably enough. In the dark, Pre-Speechbot days we tried using it and found that max would ask us to infrequently remap controller tracks when loading and saving to the same object in the scene! This behaviour was odd and rather inconvenient, but did force me into writing something that is targeted specifically to character lipsync. It was only recently when this exact issue was brought up by Martin Briedt on the Beta forum that I thought that others were finding this issue frustrating too.

Who can use this script?

People wanting to save and restore character lipsync in the form of morph data.

In fact, it can save any morph data from any object. Speechbot stores each channel incrementally, along with value data and custom key tangents. So if you base all of your characters along the same structure (ie the morh channels are the same shape target and in the same order) you can load the same lipsync or morph data onto different characters.

Who can’t use this script?

With the exception of Piers Morgan and N-Dubs, Nobody. Well, if you have a bone based facial system, you can’t. But since you can still set up a perfectly reasonable morph driven character mouth, it’s designed specifically for those types. I will probably have to develop a new system in the future that takes in the ability to store TM data from facial nodes as well as lipsync but that’s for another time.

Using the Interface

Speechbot is a macroscript, so you’ll have to drop it into your UI/Macroscripts directory. If you don’t know how to do this then you’ll have to look outside this article (there are many tutorials on how to install macroscripts but here is one)













The workflow for using Speechbot is simple –

  1. Select an object with a morpher modifer
  2. click the save button




That’s it!

When you are ready to load the data back onto the character, select the object with the morpher modifier, choose the XML file and press load





Object filter

SB_f The interface has a dropdown list of all objects in the scene with morpher modifiers applied to them, so you can pick from this dropdown rather than physically selecting it. There is a textbox where you can type common wildcard path searches, like *mouth* so that you only pick up objects with that text in their object name.

This helps if you have numerous morphers in a scene.

Working cache directory

In order to speed up the loading of lipsync data, Speechbot has a working cache directory. When you run the script, you’ll see that it will search a folder where it always looks for XML files to load. This can be set by clicking the folder icon. This stores the location and it always looks for XML files in this location. I have done this because normally an animator has a scene or scenes of characers to animate, and the lipsync XML files can be organised on the server into scenes so that the artist can set the working cache to the folder with their allocated scene at the start of the week and always get the correct files whenever they run.


If you hold the mouse over the button, you’ll be shown where the current cache directory is. If you hold SHIFT and click the button, windows will open an explorer dialog in the working cache location.





Loading/Saving to a location outside of the Working Cache Directory

With either, hold CONTROL down when pressing either load or save and you’ll be asked for a file if you want to load from another location.

Controlling key loading

Speechbot automatically saves all keys, from the entire animation range but has a few options so that you can control how the keys are loaded back onto the object.

Keep Existing Keys

By default, it clears all existing morph keys as normally you will want to replace any lipsync currently on the character, but if you want to avoid this behaviour, then hold down shift before you press load. This will keep the existing keydata. This is useful if you wanted to combine two files together, or load append some previous XML cache to the end of some other morph data.

Specify Load Range


Just as when it saves, Speechbot will restore all the keys over the entire range. However, if you just want to restore a specific time range, you can do so by clicking the Specify Load Time Range checkbox and typing a range in the spinners.



Use Offset


Occasionally, we would bump the audio forward in the curve editor to give us some more time at the start of a scene, so you can offset the key by a specific amount by checking use offset and providing a number.

Appendix – Interesting Scripting Factoids

I often wonder why these sections are called appendices. Is it because usually nobody ever bothers to read it, meaning that like the human appendix, doesn’t actually serve any purpose? (unless you count the abilty to digest grass as a good thing)

Anyway, so that I can give some scripting nuggets to anybody interested to read them, this is the place to find them.

Autonomous resource generation

It’s titles like that which put people off programming, but it’s sort of true. When you first run Speechbot, it contains a struct called LR_SpeechbotStruct. This part of the code checks if the the speechbot directory exists. If it doesnt, it assumes that this is the first time you have run the script and creates the directories and build the png image files that the dialog uses. I does this by way of constructing them from Base64 encoded strings. I wrote about this in a previous article but this is a practical example of how to use this method in a script so that you don’t have to provide any assets along with the code. If it detects that the directory is present, it assumes that the icons have been already created and doesn nothing, so it doesn’t interfere once the script has been run after the first time.

If you want to learn how to use XML to save pertinent data, take a look at the code. Since it is an XML based script, it seemed a bit silly to store dialog data to an ini file, so Speechbot uses an XML ini file. There is a method in the script for doing this so take a look and use it in your scripts too.

Download Speechbot V5

download speechbot