Main Window (visible in the output window (top/left) is the output of the upper 3 players)
OpenTZT is an Open Source 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. It also includes MIDI support. OpenTZT supports quite a few file types (avi, mov, mpg, mv1, swf, jpg, bmp) and can be extended with plugins. The project is hosted at Sourceforge.net.
|
Main Window (visible in the output window (top/left) is the output of the upper 3 players) |
Note: this documentation is still under construction. If you don't find a particular information here, please request it in the SourceForge project forum.
In order to do any first tests or tryouts with openTZT you should read the section File Organization.
Otherwise you may not be able to do anything useful with openTZT.
Consider also to switch you system color depth to 16bit (HiRes), otherwise some effects may not work.
To understand the following documentation it's good to know some basic "tzt language". The terms "material" and "clip"
are mostly used interchangeably and describe either a movie clip (avi, mov, flash), a still image (bmp, jpg) or a
special input function (DV-Grabbing, Through-Material, Generator Plugin). In any case it describes something you can put in a so called "player".
In a player you can also apply one or two effects (short: efx) to manipulate the running clip.
In the late 90' a Japanese programming god with the handle Triplet wrote TranZendenT, a wickedly cool VJ(Video-Jockey) app
and distributed it (with all Japanese documentation) as freeware. Being barely known by the VJ scene, MoRph, an australien VJ,
wrote a tutorial on VJForums.com that got people excited.
Esotic, an VJ/Programmer from North Carolina (USA), 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 a couple of programmers from around the world, lead by Esotic, started adding new
features and fixing bugs. Soon a new release, with improved MIDI and other functionality was put out on SourceForge
under it's new name openTZT.
If you haven't yet, download openTZT from SourceForge.
The installation of openTZT consists of unzipping the distribution file into its own subfolder. No install program is needed.
Unlike other programs openTZT doesn't have any project or session files which reference the actual video files.
It requires that all files that are intended for use be placed in a somewhat fixed folder structure. Files cannot 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.
The least required folder structure is already provided with the distribution.
What you need to do is copy some clips in the <openTZT_Root_Dir>\Material\Bank0\F1\.
Any of the \F1\ to \F9\ directories in every \Bank*\ folder (ranges from \Bank0\ to \Bank9\) can hold up to 17 clips.
Reading the content of the directories is done alphabetically, openTZT just ignores all clips beyond 17.
Read section OpenTZT Folder Structure for further details.
During the start openTZT first reads the tzt.ini file which is provided with the distribution. It contains the whole set of openTZT's options, set to it's default values. After that openTZT scans the \Material\, \Effector\ and \Record\ directories. As soon as the GUI shows up you can start going crazy. Try to hit some letter-keys or click on the thumbs shown in the material palette. Read the following text for a detailed description of openTZT features and control methods.
This is the main method to control openTZT. It's also the only method that provides all (except for clip scratching and BPM dragging) functionality. So openTZT is basically a keyboard controlled program. It is recommended to use a full 101 keys keyboard since the num pad plays a major part in using the effects. Laptop users who have problems with the slightly different keyboard layout should try the keyboard_lang=ENG_LAPTOP option in the tzt.ini (read section "Configuration" for further details).
Hinweis für deutsprachige Anwender: Um openTZT mit einer QWERTZ Tastatur vernünftig bedienen zu können, sollte die Option keyboard_lang in der tzt.ini auf keyboard_lang=GER gesetzt werden.
Download a detailed keyboard map (keys.pdf).
| Single Key | Left SHIFT | Left CTRL | Left ALT | Right ALT | Right CTRL | Right SHIFT | Arrow UP | |
| Q W E R T Z A S D F G H Y X C V B N |
load clips | load layer efx | ||||||
| load left efx | load right efx | |||||||
| A | start/stop APP | |||||||
| Q W E R T | start/stop APP & set loopmode |
|||||||
| U I O P [ ] J |
set overlay mode mode 1 .. 7 |
overlay mode mode 8 .. 14 |
overlay mode mode 8 .. 14 |
|||||
| M , . / | layer transition | transition speed | ||||||
| ` 1 2 3 4 5 6 7 8 9 0 - = | alpha value | value 1 left efx | value 1 right efx | value 1 layer efx | ||||
| value 2 left efx | value 2 right efx | |||||||
| value 2 layer efx | ||||||||
| 1 2 3 4 5 6 7 8 9 | set reverse speed | set forward speed | ||||||
| 0 | toggle BPM sync | |||||||
| 1 | loop mode | |||||||
| 2 | ping-pong mode | |||||||
| # | swap clips | swap clips & efx | swap clips & efx | |||||
| F1 – F9 | material page | preset page | efx page | efx page | preset page | |||
| change all banks | change all banks | |||||||
| F10 | material bank | preset bank | efx bank | |||||
| F12 | toggle output recording |
|||||||
| Cursor (left,down,right) |
select player | |||||||
| ESC | change play layer temporary |
|||||||
| BACKSPACE | hide clip | reverse play direction |
hide left efx | hide right efx | reverse play direction |
|||
| TAB | change edit layer | |||||||
| ENTER | pause/play clip | retrigger clip | ||||||
| SPACE | change play layer | apply last used layer transition |
||||||
| Numpad 0 – 9 | apply temp efx | save preset | load preset | toggle APP selection |
||||
| Numpad / | prev. temp efx page | |||||||
| Numpad * | next temp efx page | |||||||
| INS | resync bpm | |||||||
| HOME | teach bpm (press 5x) | |||||||
This table shows the english keyboard settings only. For german mapping download the keys.pdf (see above).
The following sections will show the keyboard assignments like this: A B LShift+4
This means a feature uses a group of keys consisting of the "A" for one function, the "B" for another function
and the left "Shift" and "4" pressed together for a third function. In case of Shift
(no leading L or R), both Shift keys can be used for this shortcut.
Some features also use three keys pressed together.
(LCtrl+LShift+4 sets value 2 of the left effect)
Even though many funtions can used by mouse, there are some major functions that cannot controlled by mouse (e.g. activating multiple players). On the other hand, some functions can controlled solely by mouse like clip scratching or BPM dragging.
It's also possible that using the mouse slow's down the program a little (only after clicking) since the calculation where a mouse click has occured is more complex than recognizing the key that has been pressed.
Any type of file or generator plugin openTZT can load is called a material. The material palette consists of up to 9 banks of 9 pages each. Each of these pages can hold up to 17 materials. So openTZT can load up to 1.377 materials. The Q Key is automatically left empty on all pages to be able to clear a player regardless of which page is active. The following file types are available:
Generator plugins are DLL files that can provide virtually any type of video data. Place thes dll's beneath video clips or images in the \F*\ folders. They will be loaded as any other material.
A Thru Material is a special type of material that causes the player to pass
through the video stream as it is to it's effects (see below how exactly this works).
To place a thru material in a material page simply place an file with the extension .thu in a \F*\ folder.
This file can be empty.
Live Video Capture can be enabled by creating a file with the extension .cap in one of the \F*\ folders.
This file contains the configuration for the video capturing.
This is an example file:
[setting] DeviceNum=0 UseGdi=1 dv_half_res=0 PiP=1 PiPX=0 PiPY=0 PiPWidth=640 PiPHeight=480
OpenTZT's render engine consists of two identical layers (also called "bus" in some cases). These two layers are mostly independent
and can be edited without stopping the render engine.
There are several methods to switch between these layers:
Each of the first three columns of modules are called a "player" (see screenshot pieces below). The layer effect is not attached to the 3rd player, so even if the player is hidden, the layer effect is still active. The fourth column shows the possible output devices, by default neither the clone window nor the 2nd monitor is enabled.
| material / generator |
For materials several controls are available, like playback speed, playing direction (forward, backward)
BPM-synced playback, play mode (loop, ping pong), play / pause and clip hiding.
Depending on the type of material that is loaded
different controls are available (or at least useful).
|
| effects | to be written |
| composition | See detailed description below. |
| video stream | The light blue arrows indicate that not every type of effect uses a second input stream. A few of the internal effects take advantage of this feature (e.g. layout, multi wipe) |
| output |
There are two types of output in addition to the monitor window inside the main window. A clone window which is detached from the main window and can be dragged across the desktop. Click left in the window to activate the window border. If you click with the right mouse button in that window it goes to fullscreen on the monitor it resides on. The dual display mode is designed to display the video output directly on a second monitor. Without dragging and zooming a clone window. This mode is not properly working at the moment (Ver 1.5.6) |
Players are selected by hitting one or more of the arrow keys. However, the arrow up key is dedicated to the layer effect, It is possible to perform actions on multiple Players at the same time. 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.
Two of the three players per layer are shown here. The player with the red outline is currently active,
this means if you hit a material key (QWERTY ..., see keyboard mapping) this player will receive
the material. You can also activate two or tree players at once. (be careful with playing one clip in
two or players at the same time, depending on your hard disk performance
this could easily break down openTZT's framerate).
- In the upper left corner the current playing mode is shown (play, pause, ping-pong)
- Next to the play mode is the playback speed
- In the center the clip preview image is displayed
- below that lies the pisotion gauge
- and finally, below that the current composition is displayed
In this screenhot there are also two effects loaded for each player. Below the effects you can see the effect parameters.
It depends on the effect if these parameters are used.
For a more detailed description on the effects openTZT offers, see Internal Effects.
If a material is loaded a selected player can be hidden by pressing the Backspace key.
An extended hide mode can be applied regardless of which player(s) is selected by pressing ArrowUp+Backspace.
While the normal hide will just invert each players hide state.
That means, if one of the selected players is already hidden, it will become visible while the others become hidden.
The extended mode on the other hand makes sure that every player is hidden, so an already hidden player remains hidden.
If you return from extenden hidden (hitting the shortcut again), each player's previous hide state is restored and so
the previously hidden player still remains hidden.
Clip speed and playback direction is directly coupled by the algebraic sign of the speed value.
This values is in fact the factor the normal speed is multiplied with.
If the value is 2.00 the clip speed is doubled, at 0.50 the clip at half speed, and so on.
If the value is negativ (-1.00) the clip runs backwards with the given speed.
Holding down LShift and pressing one of the
1 2 3 4 5 6 7 8 9 keys will set the speed in reverse direction.
Using RShift and 1 2 3 4 5 6 7 8 9
will set the forward speed. Press Shift+Backspace or Shift+=
to reverse the playback direction. With Shift+Backspace
Video clips can be scratched by mouse when you click on this 
area in the player
and move your mouse up and down to wind through the clip. You can use the whole area that's shown here,
so you have plenty of room to aim with your mouse.
Be aware that scratching is a difficult thing to do for a codec, so some clips might not be wound properly,
especially backwards.
Keys: J U I O P [ ] and for the alpha value: ` 1 2 3 4 5 6 7 8 9 0 - = (see key mapping for details)
Compositions are used to blend two consecutive players together. Some of the composition modes can be controlled by the alpha value.
The following explainations uses the alias A for the upper frame (right of two players) and B for the lower frame (left player).
Even if the first player (leftmost) has only the black background to combine with, it's useful for fading in and out of the clip.
(in alpha mode; works only if no other player is active or visible)
Plane U This is the default composition mode and is actually no composition at all. In this mode only A is displayed. |
Color Key Shift+U (alpha value used) to be written |
Add I (alpha value used) to be written |
Lighten Shift+I (alpha value used) to be written |
Sub O (alpha value used) to be written |
Darken Shift+O (alpha value used) to be written |
Alpha P (alpha value used) Alpha bending. Fades from B to A depending on the alpha value. (value at 6 in the sample) (` full B ... = full A) |
Screen Shift+P to be written |
Multi [ to be written |
Mulight Shift+[ to be written |
Diff ] (alpha value used) to be written |
Luminos Shift+] to be written |
Max J to be written |
Min Shift+J to be written |
Keys: Numeric keypad 0-9: LShift+<NumKey>, LCrtl+<NumKey>
to be written
The APP is used to play back some or all of your presets automatically.
Select the presets you like to be played with the grey/red dot right above the preset preview. (by mouse)
The speed in which presets are triggered is controlled with the "Trigger Delay" setting
(see image in section Using Presets).
Between those two values a randomizer chooses a different value for each upcoming trigger event.
LAlt + A - start/stop APP (current mode) (see state in status bar)
LAlt + Q - start/stop APP in loop page mode
LAlt + W - start/stop APP in rnd page mode
LAlt + E - start/stop APP in rnd all mode
LAlt + R - start/stop APP in loop all mode
LAlt + T - start/stop APP in one shot mode
Each folder such as openTZT_root_dir\Material\Bank0\F1 corresponds to one of the Function Keys
in the user interface (in openTZT called "Page" or "Material Page").
Each folder may hold up to 17 files to be played. These files will map to the letter keys WERTY ASDFGH ZXCVBN.
Q is by default skipped and mapped to "No Material" to be able to remove a material from a player.
Depending on the skip_q setting in the tzt.ini you can also load 18 files per page.
But keep in mind that you have to move to a partly or completely empty material page every time you
want to remove a clip from a player.
As you can see in the left folder structure only \Bank0\ to \Bank3\ is shown.
\Bank9\F1\ .. \Bank9\F9\ (not shown) have special purpose for effect mapping. Effects (keymap.ini or DLL) that are placed in
this folder are mapped to the numpad keys.
Any \F*\ folder can contain a keymap.ini file which tells openTZT what effect to map to a specific key.
See section Internal Effects for an example of the keymap.ini.
This folder is for openTZT's own uses and holds no user specific data.
OpenTZT comes with a quite large set of internal effects. It's no use to describe them all in detail, you just should simply try them out. Sometimes it depends on the content of the clip you applying the effect to if it produces a noticable result. For example, if you try to use the monotone effect an already black 'n white clip, you will get nothing different.
There are two different ways to apply effects to a player. The first and main way is to hold down one of the Ctrl keys
(left Ctrl for the left effect and the right Ctrl ... you know) and use the keys
Q W E R T Y A S D F G H Z X C V B N
An Effect that are applied this way will remain in the effect slot until it's replaced by another effect.
To remove an effect, just replace it with the "No FX" effect which will be mapped to
Q in every effects page.
The second way is to use the numerical keys to apply effects. These effects replace the left effect temporarily as long as the
numer key is pressed, if you release the key the previous effect will be restored.
Some of the effects use a second input stream from the previous player for rendering. These effects are called "non threadable" (NT) because they limit openTZT's multithreading abilities (only as long as they're applied). If you apply such an effect to a player, openTZT can no longer render this player in parallel to the other players. In other words, this player has to wait until the previous player has finished rendering. OpenTZT always tries to do as much work as possible at the same time, so it's also dependent on where (left or right; which player) you apply a NT effect or how you combine it with other effects.
If you don't tell openTZT how to map it's internal effects to your keyboard it will just start with Bank0/Page1(F1)/W (Q will be skipped) and distribute it's complete list of effects. You can override this with a keymap.ini file in each \F*\ folder.
Below is a sample keymap.ini for the mapping to the main effect keys.
[ Setting ] Mapping=1 # q is skipped w=Monotone(IN) e=Scanline(IN) r=Divide N(IN) t=Solarize(IN) y=Tunnel(IN) a=RotoZoom(IN) s=KaleidoScope(IN) d=RotoPattern(IN) f=LandScape(IN) g=CyclicWave(IN) h=Wave(IN) z=Zoom(IN) x=CrossZoom(IN) c=Time Divide N(IN) v=Hunsync(IN) b=Vunsync(IN) n=Hi Contrast(IN)
Since the numpad uses number keys the keymap.ini slightly differs for the \Bank9\F*\ folders:
[setting] mapping=1 1=Solarize(IN) 2=ColorBeat(IN) 3=CrossZoom(IN) 4=Change Color2(IN) 5=Vunsync(IN) 6=Reverse Flash(IN) 7=Position Wiggle(IN) 8=Divide Delay(IN) 9=Flash(IN)
Here's a list off all the effects openTZT includes, the fourth colum holds the
name of the effect you have to use for the keymap.ini files.
Effects that don't support multithreading are marked with a different background color.
| Icon | Effect | Description | Parameters | Internal Name |
|---|---|---|---|---|
 |
No fx | This is actually no real effect, it just passes the incoming image right to the output. | no parameters | none |
 |
Monotone | Desaturates the image (makes it black and white). | no parameters | Monotone(IN) |
 |
Scanline | Draws only every second line of the image. | no parameters | Scanline(IN) |
 |
Divide N | . | . | Divide N(IN) |
 |
Time Divide N | . | . | Time Divide N(IN) |
 |
Tunnel | . | . | Tunnel(IN) |
 |
Tunnel Extended | . | . | Tunnel Ex(IN) |
 |
Roto Zoom | . | . | RotoZoom(IN) |
 |
Landscape | . | . | LandScape(IN) |
 |
Landscape Extended | . | . | LandScape Ex(IN) |
 |
Kaleidoscope | . | . | KaleidoScope(IN) |
 |
Roto Pattern | . | . | RotoPattern(IN) |
 |
Cyclic Wave | . | . | CyclicWave(IN) |
 |
Wave | . | . | Wave(IN) |
 |
Zoom | . | . | Zoom(IN) |
 |
Cross Zoom | . | . | CrossZoom(IN) |
 |
Vertical Unsync | . | . | Vunsync(IN) |
 |
Horizontal Unsync | . | . | Hunsync(IN) |
 |
Water Surface | . | . | WaterSurface(IN) |
 |
Ghost | . | . | Ghost(IN) |
 |
Alpha Blur | . | . | AlphaBlur(IN) |
 |
Zoom Blur | . | . | ZoomBlur(IN) |
 |
Diffuse | . | . | Diffuse(IN) |
 |
Smooth | . | . | Smooth(IN) |
 |
Glow | . | . | Glow(IN) |
 |
Flash | . | . | Flash(IN) |
 |
Divide Delay | . | . | Divide Delay(IN) |
 |
Spiral | . | . | Spiral(IN) |
 |
Divide Str | . | . | Divide Str(IN) |
 |
Feedback | . | . | FeedBack(IN) |
 |
Jitter | . | . | Jitter(IN) |
 |
3D Rot | . | . | 3DRot(IN) |
 |
3D Bounce | . | . | 3DBounce(IN) |
 |
3D Flying | . | . | 3DFlying(IN) |
 |
3D Flying 2 | . | . | 3DFlying2(IN) |
 |
Change Color | . | . | Change Color(IN) |
 |
Position Wiggle | . | . | Position Wiggle(IN) |
 |
3D Flying 3 | . | . | 3DFlying3(IN) |
 |
3D Wave | . | . | 3DWave(IN) |
 |
3D Cylinder | . | . | 3DCylinder(IN) |
 |
3D Sphere | . | . | 3DSphere(IN) |
 |
3D ZWave | . | . | 3DZWave(IN) |
 |
Brightness | . | . | Bright(IN) |
 |
Change Color Beat | Canges clip color with BPM sync | P1=beats between change | Change Color2(IN) |
 |
High Contrast | . | . | Hi Contrast(IN) |
 |
Reverse | Inverts the image | no parameters | Reverse(IN) |
 |
Reverse Flash | . | . | Reverse Flash(IN) |
 |
Layout | . | . | Layout(IN) |
 |
Smear | . | . | Smear(IN) |
 |
Time Jitter | . | . | Time Jitter(IN) |
 |
Mozaic | . | . | Mozaic(IN) |
 |
2D Rotation | . | . | 2DRotation(IN) |
 |
Motion Edge | . | . | MotionEdge(IN) |
 |
Horizontal Wipe | . | . | HWipe(IN) |
 |
Vertical Wipe | . | . | VWipe(IN) |
 |
Color Beat | . | . | ColorBeat(IN) |
 |
Reverse Beat | . | . | ReverseBeat(IN) |
 |
Solarize | . | . | Solarize(IN) |
 |
Feedback 2 | . | . | FeedBack2(IN) |
 |
Multi Vertical Wipe | . | . | MultiVWipe(IN) |
 |
Crome | . | . | Crome(IN) |
OpenTZT can load two types of effect plugins. An openTZT specific DLL which takes advantage of all the features openTZT provides, and it's is also able to load FreeFrame plugins. Esotic has written a lot of opnTZT specific plugins. His plugins are provided along with the openTZT distribution. There's also a long list of FreeFrame plugins available on their website.
Currently all plugin effects are non threadable. Read more about multithreading and effects in the Internal Effects section.
to be continuedOpenTZT is completely configured by several ini files.
The most important ini file is the tzt.ini in the openTZT root folder.
tzt.ini parameters:
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
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
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
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)
| last change - dez 2009 | Website hosted by |  |