OpenTZT Tutorial and Reference


OpenTZT Reference



OpenTZT is an Open Source (free access to the source code) VJ tool for the Win32 platform. Utilizing DirectX, the tool is optimized to allow keyboard or mouse driven video mixing of up to 6 simultaneous clips. The project is hosted at


OpenTZT Architecture Diagram


A Japanese Programming God with the handle Triplet wrote TranZendenT, a wickedly cool VJ app and distributed it (with all Japanese documentation) as freeware. MoRph wrote a tutorial on VJCentral that got people excited. Esotic wrote some wicked effects for it and it started getting real attention.

Eventually Triplet wanted to write a new app (FireFly) and agreed to release the C++ source code for TranZendent under the GPL. MoRpH got everyone cracking. WYSIWYG wrote a python translation tool and translated the comments in the source into English and Esotic started doing his C++ thing. Beta and RC releases have been come out as we work our way towards an official 1.5 release.


The installation files for OpenTZT can be downloaded from The OpenTZT Forums

The initial release operates with 320x240 resolution. The newer Beta and RC releases operate at higher resolutions.

Installation of OpenTZT consists of unzipping a distribution file into its own subdirectory. No install program is run.

File Organization

OpenTZT requires that all files that are intended for use be placed in a fixed directory structure. Files may not be added at run-time. Many users become confused about this, but it is actually quite simple. Please review the following sections to understand this basic structure.


Videos to be played must be in a specific file hierarchy:










This is repeated for Bank1 and Bank2. Bank3 has a special purpose, it holds the startup screen in its F1 subdir (title.jpg).

Each directory such as OpenTZT_root\Material\Bank0\F1 corresponds to one of the Function Keys in the user interface. Each directory may hold up to 18 files to be played. These files will map to the letter keys QWERTY ASDFGH ZXCVBN. (Many users only include 17 per directory so that one of the letter keys maps to a blank screen as a way to empty a clip. Also see the TZT.INI section for information about keeping 'Q' mapped to a blank screen,)


Effectors use a similar structure to Materials, substituting Effector for Material in the hierarchy.

OpenTZT_root\Effector\Bank0\F1 and OpenTZT_root\Effector\Bank0\F2 have the default effectors that come installed already in them. Place any new effectors that you add in diffferent F# folders.

The association of effectors to specific keys is possible via the keymap.ini file in each F# subdir.

Here is an example keymap.ini:

[ Setting ]

r=Divide N(IN)
c=Time Divide N(IN)

Basically, as long as you get the first two lines right the last line uses the following format for each mapped effector: < Name of key >=< effector name >


This directory is primarily used to store the the images used for skinning and data files used for table lookup operations. The only thing you'll probably need to reference is this directory is the vcpWriter.EXE, which is used to set the format and codec you'll use when recording files in OpenTZT.


Below is a representative tree of the subdirectories under the OpenTZT root directory. The latest RC5 version of OpenTZT allows you to have anywhere from 3 to 9 Bank folders.

|   +---Bank0
|   |   +---f1
|   |   +---f2
|   |   +---f3
|   |   +---f4
|   |   +---f5
|   |   +---f6
|   |   +---f7
|   |   +---f8
|   |   \---F9
|   +---Bank1
|   |   +---F1
|   |   +---F2
|   |   +---F3
|   |   +---F4
|   |   +---F5
|   |   +---F6
|   |   +---F7
|   |   +---F8
|   |   \---F9
|   +---Bank2
|   |   +---F1
|   |   +---F2
|   |   +---F3
|   |   +---F4
|   |   +---F5
|   |   +---F6
|   |   +---F7
|   |   +---F8
|   |   \---F9
|   \---Bank3
|       \---F1
|   +---Bank0
|   |   +---F1
|   |   +---f2
|   |   +---f3
|   |   +---f4
|   |   +---f5
|   |   +---f6
|   |   +---f7
|   |   +---F8
|   |   \---F9
|   +---Bank1
|   |   +---F1
|   |   +---F2
|   |   +---F3
|   |   +---F4
|   |   +---F5
|   |   +---F6
|   |   +---F7
|   |   +---F8
|   |   \---F9
|   +---Bank2
|   |   +---F1
|   |   +---F2
|   |   +---F3
|   |   +---F4
|   |   +---F5
|   |   +---F6
|   |   +---F7
|   |   +---F8
|   |   \---F9
|   \---Bank3
|       \---F1
|   +---Generator
|   \---tzt_diffuse
|       \---Debug



You should now be making adjustments to the TZT.ini file using the TZTManager application. The manager app will also let you setup MIDI controllers to work with OpenTZT.


If you would like to edit the INI manually, here is the old text explaining how to do so:

Raise TZT Process Priority
When set to 1 more CPU time is allotted to the operation of TZT. Operation 
of other application become slower. Only applicable in full screen mode(?).

Start TZT in windowed mode 
When set to 1, TZT will open in a window. When set to OFF TZT will load fullscreen.

dual =0|1
Enable Dual Monitor 
When set to 1, the monitor output is sent full screen (640x480) to the 2nd monitor. 
Only operational in full screen mode. 

notext =0|1
Disable Text Input 
When set to 1, pressing both shifts at the same time results in no action. 
This disables the ability to enter text in TZT. 

Numberpad Presets 
When set to 1, the NumberPad will store and load presets. 

Enable Clone Window 
When set to 1, an extra monitor window in created and can be moved around 
(but not resized).

Enable Hardware DirectDraw Support 
Turning this to 1 may speed up TZT.

Enable Vertical Synchronization 
When page tearing becomes a matter of concern, please set to 1. 
Normally you can leave this 0.

Shift the position of the monitor view in the X (left to right) 
and Y (top to bottom) dimensions in pixels
You may need to adjust this if you are unable to set the vertical 
and horizontal positioning on your scan converter.

Decrease (zoom out) the monitor view in the X and Y dimensions in pixels
Limitations of your scan converter may require you to adjust this.

Increase (zoom in) the monitor view in the X and Y dimensions in pixels
Limitations of your scan converter may require you to adjust this.

Behavior of shift key
Behavior of the left and right shift keys can be modified. When it changes 
speed well, perhaps mode 2 is good.
        Both you have not pushed        Only the left   Only the right
Mode 0  Alpha value adjustment  Opposite refresh rate   Sequential refresh rate
Mode 1  Alpha value adjustment  Sequential refresh rate Opposite refresh rate
Mode 2  Sequential refresh rate Opposite refresh rate   Alpha value adjustment

Enable Video Bus Blend Modes 
When set to 1, when M , . and / keys are operational and cause video bus blending. 
When set to 0 the keys have no function.

Refresh frequency of the preview window (in milliseconds, with 1000 = 1 second)
Sets the renewal frequency of the preview window. The preview window can also be 
refreshed by pressing the F11 key or by selecting to edit the non playing video bus. 
The preview window is only refreshed for a video bus that is being edited but not 
currently playing.

Default BPM (1000 = 1BPM)
Sets the default BPM (in thousands). BPM has an influence on some effects. 
You can also set the BPM while TZT is running by pressing the HOME key 4 times 
(in rhythm with the music).

Enable AVI record function 
When set you 1 you can press the SHIFT+F12 keys at the same time to record the 
current monitor output to an AVI. Files will be saved to the "Record" directory 
which resides next to the OpenTZT.EXE. During a live performance you will probably
want this set to 0 as it will slow down OpenTZT and may also cause a program crash. 
You at your own risk.

Set Maximum FPS (Frame Per Second)
Setting the FPS higher may smooth the video output but CPU load is increased which 
may cause TZT to respond to keystrokes slower than you would like. You should set 
this to the maximum framerate you would ever want to achieve. 30 should be acceptable
for NTSC outputs and 25 should be acceptable for PAL outputs. If you are running VGA 
to an LCD projector 60 may be beneficial, but is probably not required for peak performance.

Enable QuickTime Functionlity 
When set to 1 allows TZT to load MOV and SWF files.

Enable Sound Functionality 
When sound function is not used, please set to 0

Enable playback position indicator 
When set to 1 the playback position of the movie is indicated, which may cause TZT 
to require higher CPU usage and thereby slow down.

Disable allotting material to the Q key 
Setting this to 1 will disable material being allocated to the Q key. 
The advantage to this is always having a quick way to clear material from a video slot. 
TZT may also load faster with this set to 1. Setting this to 0 will allow material to be 
allocated to the Q key.

Switch role of space key and ESC key 
Setting this to 1 will cause the ESC key to switch video busses and the space key 
to only switch the video bus while it is being depressed.

Select which keys you would like to use for controlling effectors. Some (laptop) 
keyboards do not have two CTRL keys, so it may be necessary to adjust this setting. 
US keyboards are not likely to contain a Hiragana key.
0 - The left CTRL key and the right CTRL key
1 - CAPS key and the right CTRL key
2 - The left CTRL key and Hiragana key
3 - CAPS key and Hiragana key
4 - Special MoRpH mode (CTRL Keys, Insert, and Mouse buttons)

0 - There is no MIDI control
1 - It cooperates with EDIROL V-4
2 - It cooperates with the general-purpose MIDI controller
Try to be able to cooperate with the T bar of EDIROL, V-4 to be able to operate mix 
with the MIDI controller.

Connected MIDI device name 
Please input all or part of connected MIDI device name. If it is EDIRL UM-1X, 
it does not care with "EDIROL" and "UM-1". It can know name from the page of 
property audio of the control panel.

0 - Same period it cannot point (? Bad translation)
1 – Effectors pages change with material pages on F1-F9
2 – Change effector pages by using CTRL+F1-F9
Task switch is made invalid 
When it turns to 1, even at the time of window mode ALT+TAB becomes invalid.

Quality of 3D effect
0 - Low Quality/High Speed - No Filtering
1 - Medium Quality/Speed - Mediam Texture Filtering (less conspicous artifacts)
2 - High Quality/Low Speed - High Texture Filtering (try reducing when artifacts are not conspicuous)
Sets the rendering quality of 3D effects. Higher settings create higher CPU loads.

Network Cooperative Mode
IP address 
Port number 1028 (fixing)
Settings for 2 person cooperative mode.

The serial number of TransZendenT which is installed
Serial number 
There are times when it becomes necessary to register users.
Deleting the serial_number from the TZT.ini will cause TZT to regeneration 
it on the next start.

Here is a representative TZT.INI file:

midi=MIDI Yoke

MIDI Configuration

All MIDI setup should be done using the TZTManager application. After selecting a MIDI device you click the Midi Learn button to start associating keys and knobs with OpenTZT key commands. This is done by clicking the row in the list to the left and then pushing/twiddling the appropriate knob/fader/key.


User Interface

OpenTZT Screenshot with UI Annotations


{Section B from the image above}

The clips are organized in 3 to 9 Banks of 9 F#'s of 18 clips each. These clips (or pix) have to be in the subdirs prior to starting OpenTZT.

F1 - F9 on the keyboard will switch between the F#'s. F10 switches between Banks of F#s. The clips are loaded by pressing the keyboard letter associated with their preview.


{Section C from the image above}

The effectors are organized in 3 Banks of 9 F#'s of 18 clips each. These effectors have to be in the subdirs prior to starting OpenTZT.

F1 - F9 on the keyboard will switch between the F#'s. F10 switches between Banks of F#s. The effectors are loaded by pressing the keyboard letter associated with their preview along with either the RIGHT CTRL or LEFT CTRL key.

The Numberpad holds 9 banks of 9 effectors as well. These effectors are stored in the OpenTZT_root\Effectors\Bank3\F# folders. The banks are cycled with the Numberpad / and * keys. Pressing a numberpad will apply that effector to the active Player only while the numberpad key is held down.

Players and Busses

{Section D from image above}

OpenTZT Players and Bus UI To be updated


Change the bus being edited by using the TAB key.

Change the bus being played by using the SPACE bar.

Use the UP arrow to select the bus effector on the bus being edited.


(Section G From Above)

Presets allow a BUS (3 players with FX) to be saved and then re-loaded into the selected bus. In v1.5 this functionality is now controlled with the numberpad (having previously been limited in older versions using J K L ; ' ]. In 1.5 you use either SHIFT and 0-9 on your Numberpad to save a preset & either CTRL and 0-9 on the Numberpad to re-load. You can have 9 banks of presets, just like the Numberpad based effectors and similarly they cycled using SHIFT and / or *

Also as an improvement on older versions All presets are saved and displayed with Thumbnails in the UI for easy recollection.


Use the LEFT arrow to select the left player on the bus being edited.

Use the DOWN arrow to select the center player on the bus being edited.

Use the RIGHT arrow to select the right player on the bus being edited.

Use the letter keys QWERTY ASDFGH ZXCVBN to assign a clip to the active player (it will have a red border.)

Use LEFT CTRL and the letter keys QWERTY ASDFGH ZXCVBN to assign a left effector to the active player.

Use RIGHT CTRL and the letter keys QWERTY ASDFGH ZXCVBN to assign a right effector to the active player.

Use LEFT SHIFT and the number keys 1234567890 to assign a REVERSE speed to the active player.

Use RIGHT SHIFT and the number keys 1234567890 to assign a FORWARD speed to the active player.

Use the letter keys UIOP[ to assign an overlay mode to the active player. SHIFT plus UIOP[ will access an additional set of overlay modes.

Notes: Be careful with the xBPM speeds. These sync the clip to the BPM and can suck up a LOT of CPU. When things start slowing down, clear out unused clips, effectors and overlays.

Bus2Bus mixing

{Section E from the image above}

To transition from one bus to another, the keys M , . / are used.

M = x-fade , = push . = wipe / = wave

CTRL-SPACE will tranistion using the last Bus2Bus Mix selected.

Note: When using the MIDI control features of OpenTZT it is possible to assign a slider to the Bus2Bus mixing to act as a T-bar between the busses. This allows for an intermediate mix between the busses instead of the keyboard generated total shift.


{Section A from the image above}

This is the same image as is in either the Clone Window or 2nd Monitor, but sized down to 320x240.


Using OpenTZT

Getting your machine ready

OpenTZT really wants you to be running in 16bit color mode. This is configured in the Settings tab of the Display Properties of your computer. If you run in 32bit, some effects will not work.

It's really good to not ask much else of your computer while it's running OpenTZT. Task Switching back and forth to it will often result in a black OpenTZT screen.

Run as few other programs as possible to free up as much memory as possible. OpenTZT will use what's available.

Prepping Your Clips

  • Make sure you actually have the codec that the clips use
  • place your clips in the appropriate subdirs as described in #File Organization
  • For the original version of OpenTZT, format all clips and pix as 320x240 or smaller.
  • Unsupported media or files in the subdirs will be ignored. (Note that supported media types with a codec that you don't have installed on your machine will crash OpenTZT on load.)
  • List of usable formats:
    • AVI
    • BMP
    • JPG
    • MOV (if TZT.INI is configured to support it)
    • SWF (if TZT.INI is configured to support it)

Displaying Images and Mixing Them

to be written

Overlay modes

The three Players in a Bus 'stack' on top of one another with the rightmost one on top. The Layering effect, or overlay mode, associated with each Player will determine how the Players below it are viewed.

This is the background image against which the foreground image (seen in Plane below) is composited:


The modes are:

  • Plane - no 'see through' at all, blocks lower levels.

This is the foreground image (set to 'plane'):


  • Add


  • Sub


  • Alpha (accepts number keys 1-0 to set Alpha fade level) - A basic x-fade

This is alpha set halfway at value '5':


  • Difference


  • ColorKey (accepts number keys 1-0 to set Black level for keying)

This is Colorkey set at value '1'


  • Lighten


  • Darken


  • Screen


  • Lumen


Operating on multiple Players simultaeneously

It is possible to perform actions on multiple Players at the same time. Normally a Player is selected by hitting one of the navigation arrows on the keyboard. If mulitple arrows are hit at the same time, the corresponding Players will be simultaeneously selected as well. Actions associated with Players will then be performed on all selected Players.

Working with BPM

A number of OpenTZT components utilize Beats Per Minute (BPM.) BPM can be setting by tapping the HOME key on the keyboard four or more times.

The priamry use of BPM is for setting the speed of clips. Players can utilize BPM in a variety of forward and reverse xBPM speeds. The clips will trigger and run at multiples of the BPM speed.

Some effectors can utilize BPM. list to be added

Using External Video Sources

The simplest way to use external video sources as if they were a video clip is to use the provided capture0.cap file. Place this file in one of the OpenTZT_root\Material\F# directories and it will appear in the clip bank with an icon that says LIVE and has a little camera.

The video source used will be the default external video source available to the machine you are on. No configuration is necessary.

If it doesn't work, check your Control Panel applet (usually somewhere in the system info) to determine what (if any) sources you may have available. Alternately you can use a tool that can do video capture like the awesome Virtualdub to check out your available video sources. If it comes up in VirtualDub, it should come up in OpenTZT.

Recording Your Output

In OpenTZT_root\SysData there is a file called vcpWriter.exe. This tool will set up the format which OpenTZT will use for recording the output. Recording the output is a CPU hog and should not be used while gigging.

You can record OpenTZT's output by hitting the SHIFT F12 key to start and stop recording.

The file will be saved in the OpenTZT_root\record folder. Note that the TZT.INI must have a recordable=1 value set for recording to be enabled.

Esotic's Effectors

Available at

Most of Esotic's effects are controlled by the CTRL-# or SHIFT-CTRL-# where # = 1-0 (okay through -) and you use the CTRL that is on the same side as the effector pocket for the effect you want to change.

Example: You put EsoticColorizer into the left effector of a player. Use LEFT_CTRL-# to adjust the hue map. Use SHIFT-LEFT_CTRL-# to adjust the brightness level.

Note: The zip includes EsoticEffectorHelp.chm, a Windows help file. Use this to get detailed understanding of each effect and how it can be adjusted.

There is also an Esotic.ini file that can be used to set the default values of the effectors. As the readme below notes, this must go into your Windows subdir (e.g., c:\Windows or equivalent.)

This is the essential part of the Readme.txt file for Esotic's effectors:

The Mask##.bmp files goes into a directory next to the TZT.Exe called "EsoticMasks". 
(EX: C:\TZT\EsoticMasks).

You can change the mask using the CTRL+SHIFT+# key combinations 

You can also Flip the layers using CTRL+<the minus key>

Please change the masks to suite your needs, but you should keep them 
320x240 with 24 bits per pixel.  White is the current video, anything 
else is the input video.  The bitmap must be 24 bit color.

There is now an Esotic.INI file that goes into your C:\Windows (C:\WinXP) 
directory.  You may edit it to adjust how the newer effectors load up.  
Basically anything compiled 2/22/04 or later.

Pete Warden's Effectors

Available at Important note: Pete's effectors use a different mechanism for adjusting their parameters. Shift+Ctrl+Number chooses which of the parameters you want to change, and Ctrl+Number sets the value of the chosen parameter.

Advanced Topics

Additional UI Components

to be written

Using Freeframe Effectors

to be written

Using the Flash Based Text Tool

A few Flash based .FLA files have been prepared that, when placed in the Materials tree, act as media that allows the user to modify text via the UI, that is then sent to the screen via a layer.

To use the text tool, engage one of the FLA files in a player and hit both LEFT SHIFT and RIGHT SHIFT at the same time to enable the text edit box. Hit them again to return to regualr editing.

Tuning the TZT.INI for Performance

Raising the process priority is a good start to improving overall performance, but it's mainly just to make sure that other apps aren't getting in the way of OpenTZT getting all the CPU Cycles it can. The main settings that may help your FPS would be "DirectX DirectDraw Emulation Mode", "Enable VSync", "Enable Playback Position", "Show Fader Values", and "3D Quality". Let's go over these in detail.

DirectX DirectDraw Emulation Mode - This tells OpenTZT to run some of the stuff that would normally happen in the GPU on the CPU instead. Turning this setting on makes a huge difference on my laptop, but not on my desktop. Try it both ways and see what works best for you.

Enable VSync - This is only really valid if you're running OpenTZT in full screen mode. Enabling the VSync should eliminate page tearing (that horizontal line when the screen refreshes in the middle of an output image update), but since OpenTZT has to wait until a Vertical Sync happens it wastes clock cycles. A more elegant solution to the page tearing problem would be nice, but as yet one has not been discovered.

Enable Playback Position - Turning this on enables the red play head indicator per clip. Writing and maintaining the playback position information may be costing your a couple FPS. Try it both ways and see if it makes a difference with your particular setup.

Show Fader Values - Like the playback position maintaining and drawing this information could be costing you frames.

3D Quality - All the 3D effects are done in the CPU as there is no real GPU integration with OpentTZT. Using a lower quality setting should help speed them up.

Using Generators

Generators act like media, they are files that are placed in the Material tree, but do programmatic things. They could be anything a programmer can make happen. They have a .DLL extension.

There are very few in existence at this time. Esotic is the only person with an actual clue about their innards.

Skinning OpenTZT

to be written

Examples of MIDI integration

Case Study #1


more to come

Case Study #2


more to come


  • If you aren't using Esotic's effectors, you are seriously missing out.
  • Keep a separate subdir tree of your Material directory structure outside the OpenTZT root. In fact, keep a couple. One should only have a clip or three. Move that one to the OpenTZT root when you want to start OpenTZT fast (the more clips it has to load the longer it takes to start up.) The value of additional Material trees is that you can custom tune them and then move them in an out of 'production' as needed for gigs and such.
  • Develop a standard idea of how to use your clip banks and F#'s. For instance, you could always use F9 in each bank to store interstitials, text, logos or such. If you get in the habit of using the banks and F#'s consistently it will save time in a gig when trying to find something special.
  • Organize your effectors so that the most commonly used group together. If you use the config switch that changes effector groups when you change clip groups, then put the effectors you will commonly use with those clips in the same F# and Bank.
  • If you find that you use the same clip mashup over and over, consider using the record feature of OpenTZT to save them as a single clip. This will save time in a gig.
  • If you're using a laptop, consider making a dedicated external keyboard with color-coded keys. It's cheap and it will make you faster. Alternately consider using something like the Nostromo Speedpad N52 to give you some extra keystroke macros and dedicated numberpad.

Troubleshooting Problems

  • The most common problem is that, while loading up clips at startup, OpenTZT dies. Watch the count very carefully to get some idea of which Bank and F# is where it fails. It is almost always a 'bad' clip that is shutting the app down. Generally it is a codec problem or some other issue. Remove the offending file and it should start. If you can't find it any other way, remove all the subdirs in the Material tree and add them back one at a time until you find the one that breaks it.
  • Long filenames cause this behavious too, try and keep filenames less than 38 characters.
  • Sometimes the whole thing gets constipated and slows to a frame or two a second. Start clearing out players and banks you aren't using. Beware the xBPM speed settings, they often contribute to this problem.


  • Triplet
  • MoRpH
  • Esotic
  • pleXus
  • Jens
  • PiedPiper
  • ?
  • You! if you start contributing to this amazing Open Source project