How to Control Animata With OSC from Max/MSP and Pure Data

If you haven´t heard of Animata yet, you should head over to and educate yourself. Download the software and go through the tutorials. I also recommend reading through the mailing list, it has tons of useful information.

Controlling Animata with a mouse and doing real-time animations is pretty cool by itself, but Animata really shows its true potential when you control it with OSC. Then you can start doing something like this:

There is a Processing example available from the Animata site that controls Animata with sound input.


Unfortunately, the Kitchen Budapest guys are busy improving the software and there isn´t really good documentation available about the OSC messages needed to control Animata. I´ll try to go through all of the available messages and give you some examples in Pure Data and Max/MSP

I assume that you know something about OSC, Pure Data and Max/MSP, because I don´t want to write a huge post explaining everything from the beginning. I´m also assuming that you have spent some time learning the basics of Animata.

One more important thing. I´m using revision 35 of Animata compiled from the svn repository. NOTE! YOU WILL NEED TO COMPILE ANIMATA FROM THE SOURCE CODE TO MAKE THE /LAYERPOS MESSAGES WORK. IT IS NOT AVAILABLE IN THE BINARY VERSION ON THE ANIMATA WEBSITE. All the other messages I´m showing here do work with Animata 003 that is available from the site. OK, let’s start.

DOWNLOAD MY EXAMPLES. Contains the Animata Scene + Max and PD patches.


All incoming messages to Animata must be sent through port 7110. The “name” in the message refers to the name of the joint, bone or layer.

Moving a joint, x and y are float values:
/joint name x y

Control the length of a bone, value is a float between 0 and 1:
/anibone name value

Switch on and off a layer, on_off is 0 or 1:
/layervis name on_off

Set the transparency of the layer, value is a float between 0 and 1:
/layeralpha name value

The next two messages require the svn version:

Moving a layer in absolute mode, x and y are the position coordinates as float values:
/layerpos name x y

Moving a layer in relative mode, x and y is the amount of pixels you want the layer to move from it’s current position:
/layerdeltapos name x y


I´m not really comfortable with Pure Data, but I was able to get all of the messages working except /layervis. I believe this is because Animata is very picky and is looking for real boolean values and Pure Data is sending integers when sending 0 or 1. This was just fixed by the Kitchen Budabest guys. The /layervis message works now. I have updated the code so please download the .zip again. You need to compile Animata again from the svn for this to work.

Pure Data to Animata

Pure Data to Animata with OSC from Matti Niinimäki on Vimeo.

There is a little problem, because Animata needs float values in the messages and Pure Data doesn’t have a separate number box for floats, so have to make sure the number you are sending is never an even number. I did this by multiplying the values by 0.999. If someone knows a better way, let me know.


It´s pretty much the same deal with Max/MSP. The /layervis doesn’t work here either. This was fixed in the svn version (>36). My Max-patch has been updated so please download again.

Max to Animata

Max/MSP to Animata With OSC from Matti Niinimäki on Vimeo.

I didn´t add the /layerdeltapos to the example patches, because it´s really easy to lose your layers somewhere outside the window.


There is also an option to send OSC messages from Animata. For this you need the SVN version. It simply works by clicking on the small OSC tick box on the Skeleton tab. The messages are sent through port 7111. The message format is: /joint name x y

Send OSC


I’ve made a plugin for Quartz Composer that makes it really easy to control Animata from Quartz Composer. Check it out over here.


Basically, any software or programming environment that is able to send OSC messages should be able to communicate with Animata.

Processing works perfectly and you can download the Sound Input example from the Animata website that will get you started. I´ll see if I can find the time to do a similar sample file for Processing also.

I’ve also had luck testing OpenFrameworks. Download the FAT version of OpenFrameworks and modify the oscSenderExample.


Whatever you want! Hook up audio input, MIDI controllers, sensors or computer vision to control real-time animations.

Check out my Mickey Mann project for an example on how to control Animata with an Arduino.

Here is the source code download link one more time.

Tags: , , , ,

34 Responses to “How to Control Animata With OSC from Max/MSP and Pure Data”

  1. Månsteri says:

    I updated the Animata scene. It was missing the arm and the mouth. So please download again if you are having problems.

  2. Månsteri says:

    I updated the .zip once again. The Animata svn version was updated with a fix to the /layervis issue. So download and compile the svn version again if you want it to work.

  3. Adler says:

    I’m used with motion apps but don’t know anything about programming… Can you explain what do you mean with compiling from SVN version and how to connect the patch to Animata? (just open the 2 apps?) I opened your OSCTutorial in Animata and tried to control trough your patch in Pd Extended but seems not to work. I also had some system crashes! (Tiger) when trying to trigger some messages… Moreover I think that a iPhone connection (trough Oscemote/Mrmr/OscTouch..) tutorial would be also appreciated.
    Thanks for your work.

  4. Månsteri says:

    Compiling from the SVN version means that you would need to download the Animata source code from

    And then you would need to compile it according to these (rather limited) instructions

    It should work with the version downloadable from Animata. Just open the 2 apps and then in PD click the message box that says “connect 7110” I think you need to modify all the number boxes to get rid of any initial error messages.

    With system crashes I can’t be really much of use. What is causing the crashes? PD or Animata? Check your console log for some information.

    I was thinking about doing an iPhone/iPod Touch tutorial also. Or maybe even writing a custom iPhone app for working with Animata.

  5. thescreamingdrills says:

    Have you got this working with Oscemote on the iphone/ipod touch? I’ve been trying to figure out osculator but I can’t get it set up right.

  6. Combover says:

    So I gather if FLTK is needed to compile animata (which seems to be mac & Linux only) I can not compile and thus run your example on windows???

  7. Månsteri says:

    Combover, as far as I know, fltk is available for windows also. Don’t know anything about compiling Animata with a Windows machine, though. You could also just use the Animata 003 binary available on the Animata website and it works with most of the stuff I have on the PD and Max patches.

    thescreamingdrills, I have used the multitouch controls of OSCemote with Animata. I set up Max/Msp to convert the messages. I’ll try to see if I can use make it work with osculator. I’m crazy busy right now, so I can’t promise to upload anything soon.

  8. Hey thanks so much for all the help with Animata and MaxMSP. Things work like a charm. I wanted to know if there is a patch for Eyesweb which sends out OSC Data between MAXMsp and Animata. I’m a student and working on a GOD Project similar to the Reverse Shadow Puppet Theatre.

    Would really be grateful if you could help or point me in the right direction… Thanks in Advance.

  9. Månsteri says:

    I have never used Eyesweb, since I don’t have a Windows machine, but this link came up on the Animata mailing list.

    This might need something in between Eyesweb and Animata to reformat the OSC messages. I think I’ve read from somewhere that Eyesweb isn’t able to send the proper messages straight to Animata.

  10. comeswithfries says:

    Any way to use animata with the Processing program?

  11. Månsteri says:

    @comeswithfries Sure you can use Animata with Processing. You need to download the oscP5 library for Processing though

    The Animata website has a sound input example for Processing in the downloads section.

  12. Leon Trimble says:

    wicked words mansteri…
    i got this working on windows, and with the pd patch being driven by OSCemote on the iPhone. all good. would love to be able to compile the svn version on windows but i’m no programmer. anyone with a pc who can help?

  13. Månsteri says:

    @leon Try asking on the animata mailing list. Someone might be able to help you there. I have no idea how to compile it on windows.

  14. Leon Trimble says:

    when i try and load that eyesweb patch i get
    ERR> Error loading patch “C:\downloads\oscman_WDM_video_input.eywx”: The item specified was not found in the collection.
    ERR> Class identifier (ClassID) of the searched item was “{3897339F-60B4-11D4-A28A-CF461A886A4A}”.
    any ideas?

  15. Månsteri says:


    I have no idea. That’s just a link I got on the mailing list. Never tested it. I saw your post on the list. Someone else might be able to help you there.

  16. John says:


    I’ve installed Animata today and I’m trying to control it with vvvv.

    I’ve studied this tutorial and everything else I can find on these pages.
    I’ve also been reading some posts on the vvvv forums about how this works:

    Is there anywhere I can get help with how to encode my OSC messages in vvvv? I can send OSC between two vvvv patches ok, but I think I am missing something when it comes encoding the OSC message in the right way for Animata to understand. For now I’m just trying to send a single ‘anibone’ message.

    I think my port is set up ok on7110, I’m using floats 0 – 1, have named my OSC encoder address ‘anibone bone1’. Attempted to convert my value to a string. But i’m a bit out of my depth.

    Also in vvvv my UDP remote host is left on it’s default which is ‘local host’. I this ok?


    • John says:

      OK animata is now definately recieveing my OSC signal, got my UDP address sorted out and I’ve figured out how to send the correct string message.

      It’s working because the ‘Lm’ property of my bone in animata is changing with my vvvv signal, and stops when I pause vvvv.

      Can’t get my actual .png limb to actually move on screen though… Still just fiddling and trying to figure out animata as I go along…

      • John says:

        🙂 I’ve worked it out. I think I was trying to do soft ik on a rigid bone setup.

        Sorry for all the posts, it took me a while to find the mailing list. I’ve started reading through the archive, any pointers to where to go next? I want to try and rig a simple face or something and map some data in vvvv (where screen size is -1 to 1) to something animata can use.

        Not clear on animata’s coordinate system. oh, and I have a UDP send on/off switch. I’ve tried leaving it on, and making it bang on each time my sytem clock ticks. Not sure how it should be set.

        thanks for putting all this out here

        • Månsteri says:

          @John. Sorry, it took me a while to reply. Been traveling and haven’t had the time to check the comments.

          The coordinate system in Animata is in pixels. When you launch Animata it will give you a window of 640×480 pixels with 0,0 in the top left corner. The thing to note is that moving or scaling the layers will change the coordinates of that layer accordingly. I usually set my Animata workspace roughly to 1024×768.

          I don’t know how the udp send in vvvv works so I can’t really help with that, but if it works by just leaving it on, leave it like that. There is no real reason to bang it if vvvv sends the message without it.

  17. Hi, I recently made an example to connect Processing and Animata via OSC.
    The Animata scene is the same in this site made by Matti Niinimäki, for a better understanding.
    You can download the files in my website:

  18. Adib Izuddin says:

    Hai there,
    does all this things, need to use MAX/MSP software? is there any alternative other than MAX? I’m a student , and I have my project doing something like this, an interactive animation controlled by audio input.
    thanks in advanced.

  19. Toon VC says:

    Is animata always listening to the first network card or does it listen to both if you have 2? Because I need it to listen to the second card.
    i’m also trying to control it from another program that has OSC function, but no luck on that. I can take in the signal from PureData, but I can’t output it in the right form towards Animata

Leave a Reply


  1. Create Digital Motion » Demos and Tutorials: Live Control of Open Source Animation in Animata, even with a ViewMaster
  2. animata gehioo « teKnotRaKiTanA
  3. temporary Very Important Things » Blog Archive » animata - real time animation editor
  4. interesting links « Digital Art & Technology
  5. Real time animation with Animata « Kr3l’s Turf
  6. Create Digital Music » Beat Blender: Actual Osterizer DJs with Real Fruit, Max, Ableton Live
  7. Product Placement « Månsteri:::[mons-te-ri]
  8. Animata