Syphon to MadMapper

This tutorial illustrates why, and when, you might want to use a standalone mapping program as your final video output from QLab to projectors, instead of using multiple surfaces within QLab.

Syphon is an open source Mac OS X technology that allows applications to share frames – full frame rate video or stills – with one another in real-time. QLab has an easily accessed Syphon server built in so it can share video with any software that can function as a Syphon client. (QLab can also function as a Syphon client so you can use other programs as an input to QLab, e.g to Syphon mobile phone cameras into QLab camera cues).

This example uses MadMapper as the Syphon client. You can download a demo version here

MadMapper works in a fundamentally different way to QLab. It takes an input video source, defined geometric areas of which can be defined as surfaces. These regions can be individually transformed, in MadMapper’s output stage,  to match an area of a projector’s output (or the outputs of multiple projectors). So a single video source playing in the input can be used on multiple surfaces, and therefore multiple areas of the projector output. This is in contrast to QLab where each video cue (even though it may use the same file as another) can only be routed to a single surface. So,  to have 3 videos on separate surfaces you need 3 video cues.

To explore why this might be a useful addition to standard QLab video operations, let’s take a simple mapping example. A stack of cubes arranged in a pyramid, 4 rows high, presents 3 visible faces of 10 cubes to a projector.


We want to map 1 video to all the top surfaces of the ten cubes, 1 to all the left visible faces and 1 to all the right visible faces. We then want to crossfade all the images to a different set of top, left, and right images.

Let’s begin by mapping one cube in QLab. Here is a video of it in action (double speed).  The video will be clearer if viewed full screen.


How it works:

  1. Create a 300×300 surface and name it Top.
  2. Duplicate the surface and name it Left
  3. Duplicate the surface and name it Right
  4. Create 3 video cues targeting the 3 videos you are going to use for the 3 visible faces
  5. Put the cues in a fire all children group
  6. Set each video cue to infinite loop
  7. In the Display and Geometry Tab assign each video cue to 1 of the visible faces
  8. Start the group cue
  9. Edit the top surface and use the corner pins to shape the video to a top cube face
  10. Repeat for the left surface
  11. Repeat for the right surface

So we now have 3 video cues assigned to 3 surfaces. This video shows the next cube being mapped:


  1. Create duplicates of the 3 surfaces of the first cube (1 at a time, I’m afraid).
  2. In the cue list, duplicate the Cue group
  3. Assign the video cues in the duplicate group to the duplicate 3 surfaces
  4. Start the duplicate group
  5. Open the Left duplicate surface.
  6. A common mistake at this point is to try and move the corner pinned surface by moving its origin by dragging the screen. This doesn’t work! As soon as you move one corner point, the corner points become the only way of shifting the position of the surface on the screen.
  7. Drag the corner points of the surface to the new position
  8. Repeat for the right and top surfaces.

You now have 6 video cues assigned to 6 surfaces.

The next video shows the state of the mapping after 6 cubes are completed. There are now 18 video cues assigned to 18 surfaces.  There are now a lot of dropped frames, so completing the bottom row may not be an option. Instead, we will create a second set of cues assigned to the already mapped 6 cubes and try to crossfade between them.


  1. Create a fire all children group and put the 6 cube group cues inside it.
  2. Duplicate this group
  3. Create a fade cue targeting the first 6 cube group cue inside the second
  4. Set the layer of all video cues in the second 6 cube  group to bottom
  5. Retarget all the cues in the second 6 cube group to  the new video files
  6. Start the first group
  7. Start the second group.

This is quite a lot of programming, and the re-targeting of many cues individually would have to be done every time we wanted the video images on the cubes to change. However, the major problem is at this point QLab is attempting to play 36 video cues simultaneously on 18 surfaces (The existing video on 3 faces of each of the 6 cubes and a further 18 cues crossfading these to the new video image). On most systems this will exceed all practical limits and, as in the example video, the program will freeze.

This is one example where QLab needs a dedicated mapping program to sit between it and the projector output. Here’s one  way to do it:

Setting up a Syphon feed from QLab (server) to MadMapper (client):

In QLab create a new empty surface 1800×600 and assign Syphon as the screen.

Syphon Surface

The Syphon server created mirrors the entire surface, so all the geometry controls are locked out.

The QLab Syphon server should automatically appear in the sources list in the right column of Mad Mapper, and this should be selected.

MadMapperSyphon Input

In QLab we create a single video cue. In our example this cue targets an 1800×600 video compositing the 3 600×600 moving images we are going to use in the mapping as a single video.(Rendered in an external video editor)

QLab1 video

When we play this cue in QLab it appears in the source image window in Mad Mapper.

MadMapper input

This video shows the steps necessary to map the first cube:


  1. A Quad is added in the Manage Surface window of Mad Mapper
  2. The Quad is resized to bound the region of the source video we want to use for the top surface
  3. The Quad is named top
  4. A corresponding Quad with corner pins  appears on the output stage of Mad Mapper
  5. The corner pins can be moved to map the quad onto the top surface of the first cube
  6. Duplicate the Quad and name the duplicate Left
  7. Move the duplicate quad to bound the second region in the source image
  8. Move the corner pins of this Quad on the output stage to map the left surface
  9. Repeat for the right surface

In Mad Mapper you can select, duplicate, move and rotate multiple surfaces simultaneously so you can quite rapidly map some more cubes


and then complete the rest:


So we now have all 3 surfaces on each of  10 cubes playing smoothly, 30 surfaces in all. QLab is coasting along as it is only playing 1 video. We can now set up crossfading to the new images. This is the equivalent of 60 surfaces of video playing simultaneously if we were attempting this only using QLab

Here it is in action:


In this example, the second set of images are not composited in an external video editor into a single file. Instead, 3 individual files are used inside a group cue, as in the QLab only mapping example. Each of these video cues is positioned on the 1800×600 Syphon surface using custom geometry so that the Syphon surface has 3 side by side images.


Again, the video performance is completely smooth. QLab is only having to play 4 videos during the crossfade.

This only really scratches the surface of what QLab in combination with MadMapper is capable of. Having mastered getting QLab to output it’s video through Syphon to MadMapper you can experiment with all the tools available. QLab and MadMapper are a very powerful and stable combination for all sorts of mapping tasks. The ability to move and rotate multiple surfaces simultaneously in a single window can really speed up many workflows. The simplest example of this would be if you set the block pyramid up in a new space and the projector was slightly out of line with the original set up. In a QLab only mapping, you would have to move all the corner points, whereas with MadMapper as your mapping system you can just select all the Quads on the output stage and move, scale and rotate them as a group, simultaneously.

Chapter Author: Mic Pool
Chapter Graphic based on a public domain illustration.
MadMapper is a trademark of GarageCUBE and 1024 Architecture.