How to use a midi controller with Imporviz

Improviz does not support Midi as default, but only OSC, so we need something that can convert Midi to OSC.

You use a commercial VJ software such ad VDMX, but that is gonna be expensive if this is the only reason to get it. ??? And we want to have it working on any of the major OSes and not just MacOS

TODO: diagram of setup

TODO: embed basic guides when appropriate

So what do you need?

Midi Controller

Some midi Controller sending out CC messages I have tested it with Akai LPD8, Novation XL and a SubZero controller In the examples we will be using the AKAI. TODO: Picture of all 3


A working Improviz installation and editor. Setting up Improviz is not gonna be covered in this guide so go to We are gonna presume you config is the default one - so start with a fresh install if you are having any issue later.

MidiGyver - Installation

As of today you will have to compile MidiGyver from the source code, but it

  • Install dependencies

    • Linux: Use sudo apt-get
    • MacOS: Use homebrew
    • Windows: dunno, let me know if you get it working and how.
    • TODO: Test on Windows10
  • Downlaod the source code from:

  • extra to a folder like your dekstop or downloads
  • open a terminal and cd to this folder
  • compile following the steps in the README

  • Watch MidiGyver Basics Part 1: Controlling shader uniforms and define keywords with ANY Midi Controller

Configure your Midi-controller to midiGyver

  • Create a config files somewhere you wont lose it either in your Improviz folder or in an MidiGyver folder

  • Change the output port from the default :8000 to :5510 in your midiGyver.yaml file (or change it from :5510 to :8000 in your imporviz.yaml)

  • Plug in your midi controller (if you have not done it allready;)

  • Now fire up Protocol or a smilar tool for detecting midi signal and take note of the messages when you turn the knob, slide the faders or press the buttons.

  • TODO: screenshot of Protocol

  • Type the right number into you yaml file

  • in MidiGyver .yaml you need to prefix name with: vars/ to make it work for improviz name: vars/fader01

Starting up Improviz and MidiGyver

Both Improviz and MidiGyver need to be started from the terminal. And they both need to be running to make this work. So fire up two terminal windows and one of these in each windows

Terminal 1:

cd [folder of your midiGyverConfig]
midigyver [myMidiGyverConfig.yaml]

Terminal 2:

cd [folder of your improviz installtion]

Using Midi input in your Improviz code

Now let us test if it works by sending something like this to improviz


This is kinda it. Have fun!

TODO: Part 2 - How to use toggle

  • use a button to toggle paintOver() with an if-then statement

  • use a series of button to select between textures/animations for your shapes

  • use a button to toggle the code-text overlay