VDMX5 is a realtime multimedia performance application.
"b8" refers to the eighth major series of builds of VDMX5. After several years of collaboration and continuous development, we've received a huge amount of feedback about VDMX5- the only way to accommodate the changes and additions requested by users was to redesign and rewrite VDMX5 from scratch with a substantially different structure and workflow. As a result of these changes, b8 is noticeably different from the builds which have preceded it- this page contains various video tutorials and documentation for the next major series of builds of VDMX5.
We've started a FAQ for b8!
We have a Vimeo album with an ever-growing number of Video Tutorials which demonstrate and explain b8's workflow. The videos are ordered- you should probably start at the beginning and work your way through. Be sure to check back often, we're always adding more!
Getting Help or Reporting Problems
- If VDMX crashes ("The Application VDMX5 has unexpectedly quit"), just relaunch it: on launch, it checks to see if it can access the internet, and if it can it will automatically send us the crash log your system generated.
- If VDMX hangs (if it's not responding and you've got the "spinny beachball") please email us a Stack Trace and anything from your console log that happened while VDMX was running.
- If you're having any other kind of problem, please file a bug report by choosing "Report Bug" from the "Help" menu.
- Please keep in mind that the faster we can reproduce whatever problem you're having, the sooner we'll be able to fix it. Describing exactly how to duplicate your problem is usually helpful- if it's easier, just record a screencast demonstrating your bug and send that to us!
VDMX is a modular, highly flexible realtime performance application. You define a layer-based rendering engine and play back (or "trigger") files on the layers, producing video streams- image filters (typically referred to as "FX") may be applied to any of these video streams, which are composited with other layers using a variety of composition modes. All of this is controlled by various UI items, all of which are deeply interactive and may be controlled remotely by MIDI, OSC, and DMX (ArtNet), or by local data sources. A series of plugins are available to add further functionality- preview windows, oscillators, audio analyzers, etc.
While the whole point of VDMX is to allow users to create their own video instruments- their own performance workflow- VDMX has a basic structure designed to help you in this task. VDMX's workflow revolves around two inspectors: the Workspace Inspector and the UI Item Inspector. These two windows form the basis of your interaction with VDMX- and, most importantly, they've been designed to be closed: when you're done using them to define your interface you can hide them, freeing up valuable screen space you can use to for your performance interface.
These inspectors serve similar, but very distinct roles. While both allow you to inspect and modify the properties of things, the Workspace Inspector is used to inspect high-level parts of the application: layers, plugins, video inputs, etc. The UI Inspector inspects and modifies the UI items found everywhere in VDMX: sliders, buttons, pop-up buttons, section presets, etc.
Your "workspace" is roughly defined as everything VDMX is doing: the project file you've got open with the files you've imported and organized, your presets, layers, video inputs, plugins, and saved resources (assets). These are the major components of VDMX: they're the high-level pieces you use to build your setup- and the Workspace Inspector is how you create and work with these pieces. The Workspace Inspector should be visible by default when you launch VDMX- it can be shown/hidden manually via the "Window" menu.
The Workspace Inspector inspects your workspace, and is split up into six sections, accessible via a series of buttons/tabs at its top: Files, Video Inputs, Assets, Presets, Layers, and Plugins. Each tab allows you to create and modify a different section of your workspace. The Workspace Inspector appears in its own window.
Much of your use of VDMX is based on your interaction with its sliders, buttons, and other UI elements, so the UI Inspector is an extremely important window because it allows you to configure these UI elements to do a variety of tasks. This will will appear automatically as you click on sliders/buttons/etc and work normally with VDMX- if it's open, it will always be inspecting whatever UI item you're working with. The window may be shown or hidden manually via the "Help" menu. The UI Inspector is just the name of a window- many different inspectors will appear in this window as you work with VDMX.
The UI Inspector is highly contextual- as you modify the UI item you're inspecting by adding data receivers/senders/etc, these additions will get inspected as you work with them for further modification. In other words, the UI inspector gets bigger and more specific automatically as you work with it- you'll never have to hunt around for an inspector for something, it will always be presented to you automatically.
The image here depicts the UI Inspector displaying the Slider Inspector- this is what you'd see if you clicked on a slider and the UI Inspector was visible.
While using VDMX, you're going to wind up creating your own windows with all sorts of things in them- FX chains, preview windows, playback controlls, etc. The Workspace Inspector and UI Item Inspector are inspectors- they float above all these other windows, because they were designed to be closed to free up room for the interface you make. In many cases, you'll be able to open items in the workspace inspector into their own windows:
Non-inspector windows- such as the one pictured at right- have a number of properties which make them easier to work with:
- Non-inspector windows "snap" to adjacent windows you're resizing or dragging them- and you can drag from the tab bar at the bottom, too. If you hold down the "Option" key while you click and drag on a window, all the windows snapped to it (and all the windows snapped to them) will be dragged at the same time, so you can move large groups of windows easily.
- Non-inspector windows can be "tabbed"- each piece of content is in its own tab, and each window can have as many tabs as you want (tabs are located at the bottom of the window). Dragging a tab out of a window will make a new window, and tabs may be rearranged.
- Tabs can be synced to MIDI/OSC/DMX/data sources- open the UI Inspector and click on a window tab, its Boolean Data Receiver will get inspected. From here, you can configure the data receiver to trigger the tab using whatever source you want.
- Non-inspector windows have a big "X" in their top-right corner: clicking this will close the tab. You can always open the tab into its own window again by inspecting it in the Workspace Inspector and clicking the "open in new window" button.
- Many non-inspector windows have a mangifying glass in their top-left corner: clicking this will inspect whatever's in the window, opening the Workspace Inspector, switching to the appropriate section (Layers/Plugins/etc), and selecting the relevant item from the list of layers/plugins.
- By default, windows can't be dragged outside the main screen (the screen with your menu bar)- you can disable this from the "Window" menu's "Keep windows on main screen" option.
- Windows can be locked in place completely via the "Window" menu's "Lock Windows" option. When windows are locked, their close and resize handles disappear and new windows can't be opened from the Workspace Inspector.
By default, the "Copy" and "Paste" commands in the "Edit" menu work with the UI inspector window: when you "copy" or "paste", you copy/paste the UI item inspected by the top inspector in the UI inspector window, which will flash to indicate that it's done something. Functionally, this means that you can click on UI items and then copy/paste them. The cmd-C and cmd-V keyboard shortcuts for copy/paste do not funciton with the Workspace Inspector. Copy/pasting isn't limited to just UI items- you can also copy and paste multiple layers, plugins, and presets at a time. Because this can potentially involve substantial changes to your workspace, the commands for copy/pasting layers and plugins are tucked away in the "sprocket" menus in their sections of the workspace inspector, where they can't be activated accidentally.
"Copy" performs a full copy of the state of whatever UI item you had inspected- all its receivers, senders, presets, etc. "Paste" works similarly,completely replacing the value/senders/receivers/etc of the inspected item with the contents of the clipboard. "Paste local" works with UI items that have local presets- it leaves the local presets of the inspected UI item alone, but pastes the contents of the clipboard's current state onto the inspected UI item.
VDMX has multiple clipboards: every item that can be copied has its own clipboard, so you never need to remember what the "last" thing you copied was. In practical terms, this means that if you copy slider A, then copy button B, you can click on slider C and paste the contents of slider A over it. This applies to copying presets, layers, and plugins, too...
While the default cmd-C and cmd-V shortcuts will work for most situations, you'll notice that every inspector that supports copy/pasting has copy/paste buttons on it. If you don't want to copy or paste the contents of the top item in the inspector- if, for example, you only want to copy a "sender" and not the entire state of the UI item- you can simply click the "copy" button in the sender inspector, inspect a different send, and click its "paste" button. This is extremely useful because everything that can be copied has its own clipboard.
Sending/Receiving Data: MIDI, OSC, DMX, and Data Sources
Receiving data from other applications or hardware and sending data from VDMX to other apps or hardware is a major component of VDMX- every UI element is capable of both being controlled via MIDI/OSC/DMX/other data sources created by VDMX and of sending its data out via MIDI/OSC/DMX. The procedure for doing so is consistent across all UI items- you add a receiver (which receives data from things) or a sender (which sends data out via MIDI/OSC/DMX) to the UI element you're working with using the UI Inspector.
A "receiver" is nothing more than an object which receives data from somewhere. Receivers can receive data from any source- MIDI, OSC, DMX, or other data sources within VDMX such as the values from an Audio Analysis plugin/LFO/clock/etc. Receivers can be found everywhere- they're used to control UI items, trigger presets, trigger tabs: they're part of the backbone of VDMX, and can be used to control nearly every aspect of the application. The receiver inspectors always appear in the UI Inspector window- if you keep it open, you may be surprised how frequently you encounter a receiver inspector of some sort- and all receivers work with Hardware Learn Mode. There are four different kinds of receivers, depending on what kind of data they provide to VDMX: boolean receivers (YES/NO), float/decimal receivers (decimal numbers, like 0.75), string receivers (letters and words), and color receivers.
A "sender" is an object which sends data to other applications via MIDI or OSC or DMX (ArtNet). The procedure for working with senders is similar to that of working with receivers- you inspect a UI item, and then use the UI inspector to add and configure your receiver (choosing MIDI, OSC or DMX, picking a data type to send, etc).
Receiver Inspector Consistency and Similarities
Because all receivers share the common goal of receiving data from somewhere, there's a certain amount of similarity in the various receiver inspectors. All receiver inspectors have a "Detect" button and a pop-up button for narrowing down the detection source to something specific; immediately to the right of these is a pop-up button with the list of existing data sources to chose from. Below these UI items is a toggle which enables/disables the inspected receiver.
Boolean receivers take an incoming numeric value (presumed to be in the range of 0.0-1.0) and converts it to a YES/NO value which may be applied to whatever owns the receiver. Boolean receivers have a number of options because it's assumed that some data sources have to be "cleaned up" a bit to work with their values.
- If your receiver is receiving a list of values via OSC, there's a text field for choosing which item in the list to use
- If your receiver is receiving from OSC or MIDI, there will be a toggle for enabling "echo" and a pop-up button for selecting the OSC/MIDI destination you want to echo values back to
- The "Threshold" slider and text field specifies the threshold of the receiver, which helps determine how the receiver responds to incoming data
- The "Toggle on Input" vs. "Val from Input" radio buttons determines the receiver's behavior
- "Toggle on Input" toggles the value of whatever owns the receiver when the receiver's value crosses the threshold value. the "Toggle on Rise" vs. "Toggle on Fall" checkboxes determine whether the receiver toggles when the value rises above or falls below the threshold (or both)
- "Val from Input" takes the received value and applies it directly to whatever owns the receiver, giving you direct control over whatever owns the receiver: if the received value is above the threshold, the receiver gets a YES, otherwise it gets a NO. If a receiver's using "Val from Input", an "Invert" checkbox appears which allows you to invert the received value.
- "Ignore Repeats" does just what it sounds like: it ignores duplicate incoming values
Floats: Decimal Numbers and Number FX Chains
Decimal receivers take an incoming numeric value, optionally modifying it via a series of number fx, and apply it to whatever owns the receiver.
- If your receiver is receiving from OSC or MIDI, there will be a toggle for enabling "echo" and a pop-up button for selecting the OSC/MIDI destination you want to echo values back to
- The "Use Num FX Chain?" toggle determines whether or not this receiver uses a number fx chain to modify the received data before passing it on to the object which owns the receiver.
- The "Edit Num FX Chain" button uninspects the receiver and its attached UI item and inspects the receiver's num fx chain, allowing you to edit and add to it.
- The "Do Math?" toggle lets you enter a basic algorithm that modifies the received values (the text field for the equation appears when enabled).
- "Scale val to fit within envelopes" takes the received value and scales it to fit within the min/max envelopes of whatever owns the receiver (usually a slider). This lets you use the full range of a hardware control to manipulate a specific range of a slider.
- "Invert val?" inverts the received value.
- "Skip duplicate received values" does just what it sounds like.
- "Ignore if this close to current val:" and its accompanying text field will optionally ignore received values unless they differ from the current value by more than the specified value.
- The middle of the Decimal Data Receiver Inspector changes depending on whether the receiver is receiving data from a MIDI, OSC, or DMX data source.
- When receiving from MIDI or OSC sources, there's an option to work with "endless" modes. Some MIDI and OSC sources send increment/decrement messages when turning infinite knobs: this is how you work with this data in the context of a slider with a finite range. Typically you pick which increment/decrement messages your hardware is using from the pop-up button, and then specify how much each "nudge" should move the slider.
- When receiving from OSC/data sources, there's a toggle for choosing whether or not the receiver's values are "normalized". By default, all receivers are expected to be normalized (the values are expected to be ranged from 0.0-1.0): if you disable this, the receiver will send its values outside this range to whatever owns it. This is particularly useful if you want to control the exact value of a slider directly.
- When receiving from OSC/data sources, a text field becomes visible which allows you to choose which item in the list you want the receiver to work with. Some OSC devices and software encodes values in lists- this lets you work around such contrivances and extract the data you need from them.
Strings: Words and Letters
There's not much to say about string receivers, because they're comparatively straightforward and rarely encountered (strings can only be received via OSC, and there aren't many applications or hardware devices capable of sending OSC string values). The inspector allows you to specify which item in a list of values to receive the string from, and optionally to echo string values back out via OSC.
Much like the String Data Receiver, the Color Data Receiver is rarely encountered and has comparatively few options- there's just a text field for determining which item in a list of values to receive from, and some controls for echoing the received color values back out.
Sending data by MIDI, OSC, and DMX
The procedure for sending MIDI data from VDMX is similar wherever you encounter it: inspect the UI item whose value you want to send, click on the "Send" tab in the UI inspector, and then create a new sender by clicking the "+" button. Once you've created a sender, you need to specify what kind of data it'll be sending- MIDI or OSC or DMX- and select a destination MIDI or OSC output. MIDI outputs are created automatically by other hardware/software- OSC outputs are created automatically if the other hardware/software makes its presence known via bonjour/zero-conf networking (VDMX supports auto-discovery of OSC services), and you can also create your own inputs and outputs manually via the MIDI preferences or OSC preferences or DMX preferences.
Sending MIDI data
Once you've created a MIDI sender and chosen the target output, the MIDI Sender Inspector appears and lets you further configure what kind of MIDI data you want to send. At the top of the inspector are three buttons which allow you to determine whether you want to send the value out as a single note, a range of notes, or a control value. As you switch between these buttons, the inspector updates itself to present a range of different options relevant to each of the different output types. If one or more of these options is greyed out or unavailable, it's because the value you're trying to send cannot be expressed with that particular data type.
- All three MIDI sending types share the common "Channel" text field to determine which channel the MIDI data will be sent out on.
- "Note" sends a single MIDI note- which note is determined by the "Note #" text field. If the value you're trying to send is greater than the threshold a noteon is sent, if the value is less than the threshold a noteoff is sent. The velocity of the note can either be static (the value specified by the text field) or variable (based on the value being sent).
- "Note Range" sends the value as a range of MIDI notes. If you're sending noteoffs, you can choose between sending the noteoff immediately, or only sending the noteoff when the next noteon is pressed (mutex noteoff).
- "Ctrl" sends a single MIDI CC value out.
Sending OSC data
Once you've created an OSC sender and chosen the target output, the OSC Sender Inspector appears and lets you further configure what kind of OSC data you want to send. At the top of the inspector are five buttons which allow you to determine what kind of OSC data you want to send.
- Usually, one or more of these data types is disabled. This happens because the item sending the data can't express its value as the disabled data type- for example, there's no "clean" way to convert a slider value (a single float) as a color, so this data type is disabled on OSC senders in sliders.
- "Bool" sends the value out as a single boolean values (YES or NO). If the value is greater than the threshold, YES is sent. An option "Invert?" toggle lets you invert the value if desired.
- "Int" sends the value out as an integer (a non-decimal number). The range of the integers being sent are specified via text fields- this output type also has an "Invert" toggle.
- "Float" sends the value out as a floating-point number (a decimal number). By default these values are normalized (ranged 0.0 - 1.0), but this option may be disabled to use the native range of whatever's sending the data. This is most commonly seen with sliders, and allows you to send the "actual" value of the slider out to something.
- "String" sends the value out as a string- a series of letters or words. This option is most commonly seen when sending the value of a pop-up button (it sends the name of the selected item).
- "Color" sends the value out as a color, using the standard OSC color data type. This option is most commonly seen when sending the value of a color picker UI item.
Sending DMX data
Once you've created an DMX sender and chosen the target output, the DMX Sender Inspector appears and lets you further configure the format of the DMX data you want to send.
The start channel lets you specify where in the target universe the values being sent should write to.
- Usually, one or more of these data types is disabled. This happens because the item sending the data can't express its value as the disabled data type- for example, there's no "clean" way to convert a slider value (a single float) as a color, so this data type is disabled on DMX senders in sliders.
- "Number" sends the value out as a single integer values between 0 and 255. The range of values can be set and an option "Invert?" toggle lets you invert the value if desired.
- "Color" sends the value out as a color, using the standard DMX color data type, RGB or CMY.
User Interface items are the bits and pieces of VDMX that you will interact with to control it. The basic set of UI items consist of sliders, buttons, pop-up buttons, and section preset UI items. These four UI elements are found everywhere in VDMX. Every effort has been made to make UI items as flexible and powerful as possible- they can all be controlled from hardware and software that sends OSC or MIDI or DMX data or from other data sources within VDMX, and they're all also capable of sending their value out via OSC, MIDI, and DMX. Every effort has also been made to make UI items as similar- and working with them as consistent- as possible, particularly within the UI item inspectors.
UI Item Similarities and Inspector Consistency
Like most things in VDMX, UI items can be inspected and modified with the UI Item Inspector- when a UI item is inspected, its outline color changes (by default to yellow, but this may be changed via the color preferences). The inspectors for the different UI items are similar in many regards, because all of the basic UI items share some common functionality: they can all be controlled by MIDI, OSC, and DMX data from other hardware/software (usually found in the "Receiving" tab), they can all send MIDI, OSC, and DMX data to other hardware/software (found in the "Sending" tab), and they all have some sort of local presets found in the "Presets" section which let you quickly save and restore the state of that single UI item. Like everything else, these inspectors are contextual- you may inspect a slider, add a receiver, then inspect that receiver to modify it further (and so on and so forth).
Sliders are UI items that describe a value within a specific range. This is one of the most common UI items you'll encounter in various FX.
- Click and drag on a slider to change its value (and inspect it), or shift-click on a slider to inspect or uninspect it without changing its value. You can also use the "Value" text field to manually enter a slider value.
- Sliders have a min and a max envelope which may be used to restrict the value of the slider to a specific range. You can adjust these envelopes by clicking & dragging on their black handles in the finder, or by holding down option (moves the min envelope) or command (moves the max envelope) while you click + drag on the slider. You can also use the "Min/Max Env" text fields to manually enter min/max values.
- The Slider UI may be locked so it doesn't respond to accidental clicks and drags by checking the "Lock slider UI?" box in the Slider Inspector.
- By default, sliders are linear- but any slider may also be made logarithmic via the "Slider mode" pop-up button in the Slider Inspector. Please note that log sliders only really "work" if the range of the slider is sufficiently large (for example, a slider ranged 0-10 won't see a very dramatic change from being made logarithmic- but a slider ranged 0-10000 will change substantially).
- Sliders can have multiple receivers- in other words, sliders can be controlled by multiple data sources/hardware controllers/etc. at the same time. Sliders use decimal data receivers, and the interface for creating, inspecting, and editing a slider's receivers is shown by clicking the "Receiving" tab in the slider inspector.
- If a slider has one or more enabled receivers, the color of the slider changes. By default it turns a light green color, but this may be changed in the "Colors" section of VDMX's preferences.
- You can disable a slider's receivers if the slider isn't visible- this is a quick and easy way to multiplex your hardware (put a couple different sliders in different tabs in the same window, sync them all to the same hardware slider- the hardware slider will only alter the currently-visible slider). Just click the "Ignore received vals if UI item isn't visible" box.
- Sliders can have multiple senders- a single slider may send its value out to any combination of OSC, MIDI, or DMX destinations. The interface for creating, inspecting, and editing a slider's senders is shown by clicking the "Sending" tab of the Slider Inspector.
- Sliders can have "marks". A mark is a defined slider value- it appears in the UI as a line on the slider, and if you click and drag on the slider it will "snap" to the mark when you get close to it. Marks are typically used to define important values- for example, the position and width sliders in a layer's composition tab, or the speed slider in the movie player controls have marks on them.
- To create or delete slider marks inspect a slider, click on the "Marks" button in the Slider Inspector, and use the "+" and "-" buttons to add or remove marks. When you add a mark, its value is set to the current value of the slider.
- Marks can be triggered via MIDI, OSC, DMX or any other data source in VDMX- when you "trigger" a mark, the slider jumps to the mark's value. To configure this, just click on the mark in the Slider Inspector- this inspects the mark, and opens a Boolean Data Receiver inspector.
- The Slider Inspector may be used to change the value of the mark- if you created a mark in the wrong place, you can enter the value you want the mark to have manually by double-clicking on the mark's value.
- Slider marks can be positioned manually (by clicking and dragging with the mouse). Just un-check the "Lock Marks" toggle in the Slider Inspector, and all the marks on every slider in VDMX will turn white and get "handles". Click and drag on one of these handles to move the mark.
- Sliders can have multiple presets, and the interface for creating, inspecting, and editing a slider's presets is shown by clicking the "Presets" tab of the Slider Inspector. Each slider preset can be triggered via a boolean receiver (shown by inspecting the preset), and the presets themselves may be inspected and modified to only change certain properties of the slider (the preset may only change the sldier's receivers, for example).
- Sliders have built-in smoothing, which can be configured under the "Opts" tab of the Slider Inspector. In addition to specifying a per-slider smoothing value, you can also elect to use a global smooth value (set in the "Sliders" section of VDMX's Preferences).
Buttons are the most common UI item you'll encounter in VDMX. There are two basic kinds of buttons: toggle buttons represent a boolean value (YES/NO, on/off, etc), while momentary buttons are used to perform actions much like any other button in any other application.
- Click on a button to trigger it (momentary buttons) or toggle its value (toggle buttons). Clicking on a button also inspects it- you can shift-click on a button to inspect or uninspect it without changing its value.
- Buttons can have multiple receivers- in other words, buttons can be controlled by multiple data sources/hardware controllers/etc. at the same time. Buttons use boolean Data Receivers, and the interface for creating, inspecting, and editing a button's receivers is shown by clicking the "Receiving" tab in the Button Inspector.
- If a button has one or more enabled receivers, the color of the button changes. By default it turns a light green color, but this may be changed in the "Colors" section of the preferences.
- You can disable a button's receivers if the button isn't visible- this is a quick and easy way to multiplex your hardware (put a couple different sliders in different tabs in the same window, sync them all to the same hardware button- the hardware button will only alter the currently-visible slider). Just click the "Ignore received vals if UI item isn't visible" box.
- Buttons can have multiple senders- a single button may send its value out to any combination of OSC, MIDI, or DMX destinations. The interface for creating, inspecting, and editing a button's senders is shown by clicking the "Sending" tab of the Button Inspector.
- Buttons can have multiple presets, and the interface for creating, inspecting, and editing a button's presets is shown by clicking the "Presets" tab of the Button Inspector. Each button preset can be triggered via a boolean receiver (shown by inspecting the preset), and the presets themselves may be inspected and modified to only change certain properties of the button (the preset may only change the button's receivers, for example).
Pop-up button UI items are used when you have to choose one from a list of several different choices. To save space, the different choices are presented to you as a menu which appears when you click on the pop-up button. Among other things, pop-up buttons are used to let you choose composition modes, browse lists of FX, choose video sources, etc. Like all other UI items in VDMX, pop-up buttons can be controlled via MIDI, OSC, DMX, or other data sources in VDMX.
- Click on a pop-up button to display its contents as a menu (this also inspects the pop-up button). This menu may be hierarchical (may have multiple levels). Shift-click on a pop-up button to inspect it without displaying its menu.
- The "Menu Items" tab of the Pop-Up Button Inspector lets you configure the receivers on the individual menu items. Every menu item in a pop-up button has its own boolean data receiver- which means you can use MIDI, OSC, DMX, or other data sources in VDMX to trigger the menu items directly. Just click on a menu item to inspect its receiver.
- The contents (the menu items) of some pop-up buttons are editable- the "+" and "-" buttons in the "Menu Items" section of the inspector are enabled in these pop-up buttons. At the time of this writing, the only editable pop-up buttons are in the "Control Surface" plugin (you can make custom menu items in any pop-up buttons you create).
- The "Navigation" tab of the Pop-Up Button Inspector lists a number of built-in receivers that control the selection of the pop-up button. There are receivers that let you move the selection up and down within the menu, choose random menu items, choose menu items with normalized data, choose menu items by item index, or choose menu items by sending a string (via OSC) with the name of the item. As with any receiver, these can all be controlled by any data source in VDMX or data received from MIDI or OSC or DMX controllers.
- If a pop-up button has one or more enabled receivers (including its navigation receivers), the color of the pop-up button changes. By default it turns a light green color, but this may be changed in the "Colors" section of the preferences.
- Pop-up buttons can have multiple senders- a single pop-up button may send its value out to any combination of OSC or MIDI or DMX destinations. The interface for creating, inspecting, and editing a pop-up button's senders is shown by clicking the "Sending" tab of the Pop-Up Button Inspector.
- Pop-up buttons can have multiple presets, and the interface for creating, inspecting, and editing a pop-up button's presets is shown by clicking the "Presets" tab of the Pop-Up Button Inspector. Each preset can be triggered via a boolean receiver (shown by inspecting the preset).
Section Preset UI Items
Section Preset UI Items are used to provide you with an interface for quickly saving and restoring presets which only affect a specific and limited area of the application. For example, Section Preset UI Items are found in many plugins- these presets affect only the specific plugin they appear in (the section preset UI item in the audio analysis only affects the audio analysis, etc). They're unobtrusive- particularly when they're empty- but section preset UI items are found in a lot of places within VDMX. Section Preset UI Items are just another kind of preset- different artists have different workflows, so VDMX offers as many different kinds of presets as possible.
- Shift-click on a section preset UI item to inspect it without triggering or updating any of its presets.
- Clicking the "+" button on the right side of a section preset UI item creates a new local preset. The new preset is given a name by default and appears as a button starting on the left-hand side of the UI item.
- Clicking directly on a preset in a section preset UI item will either trigger the preset (read the preset) or update the preset (write the preset). The action that is taken is determined by the "R"/"W" toggle button on the far right of the section preset UI item. If the button says "R" then clicking on a preset will trigger it; if the button says "W" then clicking on a preset will update it. You can also configure the Section Preset UI Item to automatically disable writing after updating a preset via the "Section Presets" entry in VDMX's Preferences.
- If you make "too many" presets, two buttons will appear within the Section Preset UI Item ("<" and ">")- these buttons let you page back and forth between your presets.
- Like pop-up buttons, section preset UI items have navigation receivers that let you navigate their presets (trigger next/prev preset, trigger random preset, trigger preset by name, etc). These navigation receivers are listed in the "Navigation" tab of the Section Preset UI Item inspector.
- Each preset in a section preset UI item has a receiver attached to it. This means that each preset in a section preset UI item can be triggered directly from any MIDI/OSC/DMX/Data source.
- The "Presets" tab of the Section Preset UI Item inspector lists all the presets. From this panel you may inspect the receiver attached to each individual preset. You may also update the inspected preset from this tab.
- Section Preset UI Items can have multiple senders- a single UI item may send its value out to any combination of OSC, MIDI, and DMX destinations. The interface for creating, inspecting, and editing a preset item's senders is shown by clicking the "Sending" tab of the Section Preset Item Inspector.
UI Items and Soft Takeover
When you use a hardware controller (that sends MIDI, OSC) to send values to a UI item in software, one of the conceptual problems you may encounter is the "jump" between the hardware value and the software value. For example, let's say you have a slider in VDMX- the value of the slider is 0.75, and it's receiving from a slider on a MIDI controller you're using. if the MIDI controller's value doesn't match the slider's value, as soon as you move the slider on your MIDI controller the slider in your software will "jump" to the hardware value. This "jump" is considered undesirable by many artists, and soft takeover is how you prevent it.
Generally speaking, soft takeover is the name given to a series of options that let you prevent or work around this jump. Since sliders and buttons are at the forefront of hardware/software interaction, sliders and buttons both offer soft takeover options. For each UI item, different soft takeover settings may be used if the values are being received from a MIDI or OSC controllers, or data sources from within VDMX. All soft takeover settings are global (affect all sliders or all buttons, respectivaly), and are found in the "Sliders" and "Buttons" sections of VDMX's preferences.
Each set of "soft takeover" settings offers four different soft takeover modes:
- "Off"- If you click and change the value of a VDMX slider receiving from a MIDI slider, the VDMX slider's value will stay to whatever the value was set by your mouse. When you move the MIDI slider again, the VDMX slider will "snap" to the MIDI slider's value. Soft takeover is off- the value of the VDMX slider is the last value it was set to, either by your mouse or your MIDI slider.
- "Immediate"- If you click and change the value of a VDMX slider reciving from a MIDI slider, the VDMX slider's value will immediately snap back to the last-received value from the MIDI slider as soon as you release the mouse button.
- "Pickup"- If you click and change the value of a VDMX slider receiving from a MIDI slider, the VDMX slider's value will stay to whatever the value was set by your mouse. When you move the MIDI slider again, the VDMX slider's value will stay where the mouse left it- until your MIDI slider gets close to the value of the mouse slider, and you "pick up" the VDMX slider's value with your MIDI slider. The pickup tolerance determines how close the MIDI slider's value has to get to the VDMX slider's value before the pickup occurs.
- "Fade"- If you click and change the value of a VDMX slider receiving from a MIDI slider, the VDMX slider's value will smoothly start fading back to the last value received from the MIDI slider. The speed it fades back is determined by the "fade speed slider"
Keep in mind that there's a set of these options for controlling soft takeover for both MIDI/OSC and internal data sources, and sliders and buttons each have independent sets of soft takeover settings!
UI Items and Their Presets
The most commonly used UI items- sliders, buttons, and pop-up buttons- each have their own set of presets. Each of these UI items has its own set of presets which affect that UI item and only that UI item. Pictured at right are several UI items that each have local presets (if the text of a local preset is green, it's because that preset's receiver is enabled).
- The main place you will interact with presets local to UI items is in the UI item's inspector: Slider, Button, and Pop-up button inspectors all have a "Presets" tab which lets you inspect, edit, create, and delete presets for that specific UI item.
- These UI items can have as many different presets as you want/as you can fit in there. The presets appear as "buttons" in the UI item- clicking on one of these buttons will trigger it and restore the preset. The preset "buttons" work with hardware learn mode, and you can also "drag and drop" data sources onto them.
- Like the section preset UI item, each preset has a receiver attached to it which may be used to "trigger" the preset via a data source or other MIDI/OSC/DMX source.
- Presets for some UI items may be inspected, and the scope of the preset may be changed. For example, a slider-specific preset may be configured to only change the slider's "senders", or only change its "receivers". The most common use of this is multiplexing: setting up a series of different presets that tell the slider to switch between different receivers/different data sources.
UI Items and Hardware Learn Mode
Hardware learn mode is the fastest way to set up a bunch of UI items to receive data from a MIDI, OSC, or DMX data source. Hardware learn mode (HLM) is activated via the "Workspace" menu ("Hardware Learn Toggle", or cmd-L)- when enabled, every UI item that works with HLM turns bright blue. Just click on a blue UI item and wiggle the appropriate control on your MIDI/OSC/DMX device- VDMX will automatically configure your UI item to receive from the control you moved. If you change your mind, just wiggle a different control. Hardware learn mode will stay enabled until you explicitly disable it via the same means- so you can set up a bunch of UI items without interruption.
If you just want to quickly synchronize one UI item to a MIDI or OSC or DMX slider, you can also take advantage of the single-shot hardware detect: if you select this menu option (or its command-key equivalent, cmd-D) and then wiggle a MIDI or OSC or DMX source the presently-selected slider/button/receiver will automatically be synchronized to your control. If you inspect a different UI item the detect will be cancelled- and the detect will also be canceled immediately upon receipt of control data from a MIDI or OSC or DMX source.
It's worth noting that both of these function via receivers. While hardware learn mode has the function of letting you quickly synchronize UI items in VDMX to MIDI or OSC or DMX data, this is accomplished via receiver inspectors (and is why their inspectors turn red- technically, the receiver inspector is what's doing the detect). The implication of this is that hardware learn mode actually works with *any inspected receiver* in VDMX- any receiver in any UI item can be immediately synchronized to your hardware just by inspecting it and wiggling a control...
Syncing UI Items to Plugins by right-click dragging
"Detect" and "Hardware Learn Mode" are great because they offer a simple and fast way to create a mapping between an input device and a property in VDMX. There's a similarly direct way to create a mapping between data sources created by plugins in VDMX- many plugins allow you to create connections to their data sources by right-click-dragging (or ctrl-click-dragging) from the data source to the UI item you want to use it. As you do, you'll notice a red arrow going from the source of your drag to your mouse cursor, and as you mouse over UI items they'll turn red, indicating that they can accept the drag.
- If you dropped onto a slider or button, the first receiver in the slider/button will automatically be set to the data source you dragged from (a receiver will be created if one does not already exist).
- If you dropped onto a pop-up button, the "Choose by float" nav receiver in the pop-up button will be set to the data source you dragged from.
- If you dropped onto a local preset in a slider/button/pop-up button or onto a local preset in a section preset UI item, the receiver used to trigger that preset will be set to the data source you dragged from.
- Clock plugin: right-click-drag from anywhere in the dial to sync the drop target to the measure position of the clock
- Control Surface plugin: right-click-drag from any slider, button, or color wheel to sync the drop target to the value of that slider/button/color wheel.
- Cue List plugin: right-click-drag from any cue to sync the drop target to the value of that cue's data source
- Data Looper plugin: right-click drag from the "preview" of any wave ("View All") or from the editor to sync the drop target to the value of the dragged track.
- LFO plugin: right-click drag from the value bars on the left or from any wave in the preview to sync the drop target to the value of the dragged LFO.
- Step Sequencer plugin: right-click drag from the leftmost column (the "track name" column if the plugin is in "View All" mode, the step value column if the plugin is viewing a single track) to sync the drop target to the value of the dragged track.
UI Items and Echo Mode
Many MIDI and OSC devices support the ability to update their UI by sending them MIDI or OSC data. For example, many MIDI controller consist of grids of light-up buttons- the buttons can be lit up (and frequently, their color changed) by sending the controller MIDI data. Another example would be OSC-based software- such as Lemur, or TouchOSC- updating the slider on a touchscreen UI by sending it OSC data.
- Sliders, buttons, and pop-up buttons in VDMX all have the built-in ability to automatically "echo" their value back out to the MIDI or OSC device they're receiving from. Simply make sure the "Enable Echo on all Receivers" checkbox in the Slider/Button/Pop-Up Button Inspector is checked.
- Echo only works if the UI item is receiving from a MIDI or OSC source.
- Functionally, "echo" is set on a per-receiver basis- if your UI item is receiving from multiple receivers, this allows it to echo its value back out to all it sources.
- You can also change which device a given reciver echos its value back out to- by default this should be set to the source from which the MIDI data was received.
- If you're using MIDI Note On/Off messages to control your UI item, VDMX allows you to customize the velocity value accompanying the note. On several pieces of hardware, this is how you change the color at which the corresponding MIDI button lights up.
Rendering: Layers on a Canvas
VDMX has a layer-based rendering engine- if you're familiar with photoshop, then you're familiar with the basic rendering model VDMX uses to produce its output:
- Layers are the basic building block of this rendering engine. Each layer has a source (and only one source) which is some sort of media file (QT movie, QC composition, image file, etc) and an "FX Chain" which is a series of image filters that are applied to the video stream being produced by the layer's source. The post-FX chain video stream is then composited in the canvas using the layer's size, position, and composition mode (typically a CoreImage composition filter similar to a photoshop blend mode, but OpenGL and Quartz Composer comp modes also exist).
- A "group" is a combination of one or more layers that are composited together to produce a single image which is then treated as a layer (it has its own FX chain and composition settings, and is subsequently composited with other layers). This sort of hierarchical rendering is similar to flattening a couple of layers together in photoshop, and then taking that flattened image and re-compositing it with other layers.
- The "Canvas" or "Main Output" is the image VDMX is rendering for output. A canvas has an explicit size, and is treated like a group- all the canvas' sub-layers are composited (or "flattened" to use the photoshop metaphor) within the canvas to produce an image which is then run through the canvas' FX chain (a series of image filters which modify the image).
Layers are created, inspected, edited, rearranged, deleted, grouped, and generally controlled via the "Layers" tab in the Workspace Inspector. Most importantly, clicking on a layer or group in the list of layers will inspect that layer. If the layer's components haven't been opened into independent windows they will be displayed in the workspace inspector window, where you can interact with them. If the layer's components have been opened into other windows, their tabs are activated so the components are made visible in your interface.
The Workspace Inspector and Your Layers
- The "MASTER FADER" at the top of the workspace inspector is the master fader for your output. This is a quick way to fade to black.
- Immediately below the master fader is your list of layers. The "Canvas/Main Output" cannot be deleted or rearranged- your canvas is the final image being produced by VDMX's rendering engine. If a layer is a group, it can be expanded to display the layers inside it.
- Clicking on a layer in the list of layers will inspect that layer, showing its source, fx, and composition interfaces.
- To create a layer, click the "+" button.
- To delete layers, select them in the list of layers and click the "-" button.
- To rename a layer, double-click its name in the list of layers.
- If you click and drag a layer in the list of layers you can change the order of the layers- you can also drag layers into and out of groups in this manner. Changing the order in which layers are composited can change the look of your output dramatically- it all depends on the composition modes you're using.
- Clicking on the "sprocket" button opens a pop-up menu that allows you to perform several layer-based actions:
- If you select one or more layers and choose "Group Selected Layers", a new group will be created and the layers that were selected will be placed inside it. The layers inside this group are composited together to produce a single image- the group image- which is then composited with the other layers alongside the group.
- "Copy Selected Layers to Clipboard" is self-explanatory: the selected layer or layers are copied for later pasting. If you copy a group, the group and all its sub-layers are also copied.
- "Paste Clipboard to New Layers" takes the layer or layers currently on your clipboard and creates new layers from them. If the clipboard contained a group, the group (and all its sub-layers) will be pasted into the layer.
- "Duplicate Selected Layer" makes a copy of the selected layer.
Layers, In Detail
Functionally, layers have three discrete components: source, fx chain, and composition settings. Each of these components has its own inspector in the workspace inspector window, and each component may be moved from the inspector into its own window should you decide you want its UI in a more prominent location.
The layer source displays controls for controller the media file being used as the layer's source. In addition to various source-specific interfaces, the layer source has a couple dedicated UI items that don't change.
- The "Size:" text fields describe the resolution of this layer. Some media types- like QC compositions, or CI generators for example- can be resized, in which case these fields are editable.
- If multi-threaded rendering is enabled, the "FPS" field determines how fast the layer is rendering.
- The "Eject" button ejects the current source- with no source, the layer doesn't appear in the canvas/main output.
- The "Use Source:" pop-up button contains a list of built-in sources. This is an incredibly useful pop-up button because it lists every video generator and video stream available to VDMX- a huge number of sources- and lets you immediately start using any of them with one click. This pop-up button contains:
- Any connected digitizers made available via QuickTime
- Built-in CoreImage "generators"- these are included with your system (and may be downloaded from 3rd-party developers)
- FreeFrame and FreeFrame GL generators
- QC sources in VDMX's application support folder, which are treated as simple image/video generators
- Syphon sources published by other applications
- The rendered images of other layers and groups, including the canvas (both pre- and post-FX)
- Video sources published by QC plugins in your workspace
- Web sites
- New text files
- Windows in other applications may be used as video sources
Layer FX Chain
An FX chain is a series of image filters (or "FX"). Each of these filters is passed frames of video which they modify somehow, and the filters are applied one after the other (the output of the first filter is given to the input of the second, and so on). The filters themselves can be CoreImage filters (included with your system and available for 3rd-party download or purchase), FreeFrame (1.0) or FreeFrameGL (1.5) filters, or QC compositions with the appropriate image inputs (included with VDMX, available for download, and you can easily make and customize your own).
The Layer controls in a Layer FX window are relatively sparse:
- The "Load Asset:" pop-up button lets you load a video fx chain asset (a saved video fx or chain of video fx). The vid fx assets may be customized and enabled/disabled via the Workspace Inspector's "Assets" tab.
- The "Replace"/"Add" toggle determines whether the assets you load entirely replace the FX chain or are just added to the end of it. By default this is "Replace", but you can change the default setting in the "Misc." section of VDMX's preferences.
- Immediately below the "Replace/Add" toggle is a "Save Asset" button- if you click this, the contents of the current FX chain are saved as an asset and may be recalled via the pop-up button in this and all your other projects.
- The Section Preset UI item in the Layer FX Window lets you quickly save and restore the contents of the FX chain.
There are a lot of different FX installed on your system and even more available for download, but all FX share certain common characteristics.
- All FX have an "On"/"Off" toggle which immediately bypasses/disables the effect. If this is "off", the effect isn't being passed any video data or processed in any way. By default, FX are "on", but you can change this default on an effect-by-effect (actually, asset-by-asset) basis or globally in the "Assets" section of the Workspace Inspector.
- All FX have a "Wet/Dry" slider which fades the effect in and out smoothly. If this slider is 0 (if the effect is faded all the way out) the effect won't be passed any video data or processed in any way. Again, the default is for this slider to be "1" (faded all the way in) but you can change this on a per-effect basis via the "Assets" section of the Workspace Inspector.
- All FX have a pop-up button with a list of composition modes- when you use the "Wet/Dry" slider to fade FX in and out you're actually compositing the pre-FX video stream with the post-FX video stream, and this lets you choose the composition mode. All the composition modes available to layers are available to FX (even the modes that use QC compositions to render timelines or animations).
The composition controls of a layer determine how that layer is displayed within the canvas (or its parent group). This is broken up into three basic groups: how it gets composited with the layers below it (layer opacity and composition mode), how the image is sized and positioned in the output (rect or quad perspective map), and how the source image is cropped before display.
- The "Layer Opacity" slider sets the opacity of this layer. In most composition modes, this is handled by modifying the alpha of the video stream produced by the layer, which is then composited with other layers using the composition mode.
- The "Show/Hide" toggle next to the layer opacity slider is an independent control for quickly showing/hiding your layer. In older versions of VDMX, this would actually change the layer opacity slider value- this is no longer the case.
- The "Composition Mode" pop-up button lets you select the composition/blend mode used to composite this layer with whatever's below it.
- By default this is "OpenGL-Add": the GL blend modes are fast, but they aren't terribly interesting. If you click on this pop-up button you'll notice two subcatgories:
- "CoreImage" contains CIFilters in the "Composite Operation" category, many of which are familiar as they're comparable or in some cases identical to photoshop blend modes. By default, OS X ships with a bunch of CI comp modes, and more may be downloaded or purchased.
- The "Quartz Composer" category contains QC compositions in VDMX's "Application Support" folder- these compositions publish two image inputs (top and bottom image) and a number input (opacity) and are useful for making your own composition mode (transitions are especially easy to do in QC). VDMX ships with a bunch of sample QC comp modes, and you can easily download and make your own.
- The "Comp. UI tab" shows any custom input controls for Quartz Composer or Core Image based composition modes.
- The "Crop" tab shows the amount of the source image that will be cut off from the left, right, top, and bottom of the image before being sized and positioned in the output.
The Size & Pos tab in the composition controls can be switched between the simple "Rect" mode and "Quad" perspective warping.
Simple / Rect Mode
- The "X Position" and "Y Position" sliders describe the position of the layer within the canvas (or the layer's parent group). The units of these sliders is pixels, and by default both of these sliders should have a mark designating the "center" of the canvas.
- The "Position Mode" pop-up button sets the range of the position sliders.
- In "Offscreen" mode, moving the X or Y position slider all the way to the left or right will move the layer completely offscreen.
- In "Onscreen" mode the position sliders will move the layer left or right, but ensure that the layer doesn't get moved offscreen.
- "Center" mode splits the difference: move the position sliders all the way to the left/right will move the layer halfway off the canvas.
- The "Width" and "Height" sliders are size multipliers- a value of 1.5 will make the slider one and a half times larger in that dimension. By default, these sliders have marks at 1x.
- The "Size Mode" pop-up button lets you adjust the default size of the layer within the canvas.
- "Fit" makes the layer as large as possible within the canvas without cropping it or changing its aspect ratio (so you may see some letterboxing if the layer's aspect ratio doesn't match the canvas' aspect ratio).
- "Fill" makes the layer's deafult size large enough to fill the canvas- the layer's aspect ratio isn't changed, so there may be some cropping.
- "Stretch" makes the layer completely fill the canvas, distorting its aspect ratio if necessary.
- "Copy" does a simple 1:1 pixel copy- the "size" and "width" sliders are ignored, and bilinear filtering is disabled in the rendering engine. If you need pixel-perfect image reproduction with no interpolation in your output (bitmap art is one of many applications) you may want this mode.
Perspective Mapping / Quad Mode
In Quad mode the output layer is not limited to a basic rectangle shape- each of the four corners of the layer can be moved to create a perspective distorted image that can be projected onto a skewed surface.
- Drag handles in the position viewer to set the locations of each corner. Clicking on a handle will also inspect it in the UI inspector window where you can type in specific coordinates for the vertex, or assign MIDI/OSC/DMX data-sources to change the x and y location of the point. The arrow keys can be used to nudge the selected handle 1 pixel at a time.
- The "+" and "-" buttons zoom the handle position interface in and out.
- The "Reset" button returns the handles of the quad to their respective corners.
A group is a way to take several layers, composite their video streams together, and treat the resulting video stream like any other layer (you can apply fx to the composited image and then composite it with other layers). In the parlance of photoshop, groups are what happen if you flatten a bunch of layers together, and then treat the flattened image as another layer. A group in VDMX is treated just like a layer- the resulting image has its own FX chain, layer opacity slider/composition mode/etc- you can even explicitly set the resolution in pixels and framerate at which the group's video stream is rendered. Practically, this sort of general, hierarchical approach has numerous advantages- from masking to feedback to positioning.
The "Canvas" is, for all intents and purposes, a group: it has an explicit resolution and framerate, its layers are composited together and the resulting video can be processed by adding FX to its video FX chain. Because the canvas is the top-level group, however, there are a couple important differences:
- You can't delete or rearrange the canvas
- By default, canvas rendering is skipped on many machines (this option is found in the "Rendering" section of VDMX's preferences). Instead of explicitly rendering the canvas to produce an image (which is then displayed onscreen), it's faster just composite the canvas' layers directly in your output window (or secondary display/s). This skips a rendering step and can increase your framerate (especially on older machines), but this approach has several important drawbacks:
- If you're skipping canvas rendering, there's no canvas image for you to preview.
- If you're skipping canvas rendering, you can't send the canvas image out via Syphon.
- If you're skipipng canvas rendering, you can't apply FX to the canvas video stream.
- To change the resolution of the canvas, inspect it in the Workspace Inspector- use the "Rez" text fields in the "Group Controls" window set specify the resolution in pixels. The controls for changing the default resolution of the canvas (when you make a new project or launch VDMX, this resolution will be used) are found in VDMX's Rendering Preferences.
- By default, the framerate of the canvas is driven by the refresh rate of your screen on many machines. Instead of rendering the canvas its own thread this draws the canvas every time the display connected to your computer redraws itself. In many cases this results in a faster framerate than most people might expect, which looks smoother- but it also means that you're asking your computer to do more work, and it effectively prevents you from manually setting the framerate (which may be a good thing: this is the default for a reason). The "Display Drives Canvas Rendering" setting in VDMX's Rendering Preferences lets you adjust this.
VDMX is a realtime video application- it's dealing with a bunch of video streams simultaneously, applying FX to them and compositing them with one another. Because this is all software-based, it's possible to do all sorts of crazy video routing: every layer in VDMX "publishes" its most current image (both pre- and post-FX) in much the same way that a data source would publish a value. Even the "Canvas/Main Output" image is published. Elsewhere in VDMX there are UI items for receiving video streams- FX that let you apply an outside video stream as a mask, for example- that let you choose one of these video streams from a pop-up button list of choices. You can even use one of these video streams as a layer source (with all the feedback possibilities that entails).
There are a variety of different video sources available in VDMX- in addition to the video streams for all your layers and groups (both pre- and post-FX) in your workspace, any video inputs (either digitizers or windows in other applications) you've enabled in the workspace inspector are available. If any other apps are publishing images via Syphon, these sources are also listed by default (you don't have to enable anything for Syphon inputs). If you've loaded any QC compositions as plugins, their main output- as well as any published image outputs- are made available as video streams in VDMX. There are also all the expected "image generators" for the various filter formats VDMX supports (CoreImage, FreeFrame/FreeFrameGL, and Quartz Composer).
All of these video streams are, by default, only available to VDMX. If you want to make these video streams available to other applications, all you need to do is create a Syphon Output plugin (you only need one, a single plugin can send multiple video streams) and choose which video streams you want VDMX to publish via Syphon.
There are three different ways to send video to VDMX from other hardware or software. If you want to inspect or edit any of these inputs, click on the "VidIn" tab of the Workspace Inspector and then use the pop-up button to select the type of inputs you want to work with ("Digitizers/Capture Hardware" or "Window in other Applications").
- Syphon is a mac-specific technology that allows applications to share video with one another. Syphon is fully integrated- any video sources published by other applications are automatically made available to VDMX. There's no setup required in VDMX.
- Digitizers and Capture Hardware are hardware devices- USB inputs or PCI cards- that digitize a video input (component, composite, s-video, etc) and make the resulting video stream available for use within VDMX.
- Windows in other Applications may also be used as video sources in VDMX.
VDMX supports the use of digitizers, capture cards, and other video input devices via QuickTime- as long as your device is QuickTime-compatible (and nearly all mac-based capture cards are), it will work seamlessly in VDMX. Unlike Syphon inputs, video digitizers come with an explicit cost- processing video from a digitizer usually makes more work for your CPU (sometimse a lot more- it depends on the digitizer), so by default video digitizers are disabled. Triggering a disabled video input- or selecting it from the "Use Source:" pop-up button located in every layer source- will automatically enable it with its default settings.
Clicking on a video digitizer inspects it- the inspector for a video digitizer lets you modify its options. If the video digitizer's running, this also displays a preview of its video stream in the workspace inspector.
- "Add File to page:" presents you with a pop-up button listing all the pages in your workspace. As you record clips from the inspected digitizer, they will automatically be added to the selected page.
- The "Record" and "Image" buttons let you start/stop recording from the input or take a snapshot of the input and store it as an image, respectively. Immediately below these buttons is the recording duration, expressed in SMPTE. The settings used for recording files directly from video inputs- including the location of the saved files- are found in the "Recording" section of VDMX's preferences.
- The "Use Device Codec" toggle determines whether or not VDMX uses the default code for your digitizer when saving the video to disk (by default, VDMX uses the device codec). Not using the device codec makes extra work for your CPU, but may be appropriate under some circumstances (for example, your drive may not be fast enough to keep up with recording uncompressed HD video to disk- transcoding it might be a good idea). If you aren't using the device codec, the codec to use is set by the "Recording" section of VDMX's preferences.
- The "Rez" and "FPS" fields let you attempt to set the resolution and framerate of the inspected digitizer. Running at full-resolution is usually a good idea because changing the resolution makes more work for your machine- if you're going to change the resolution, halving it (or quartering it) is usually faster than resolution changes which aren't an even multilple of 2.
- The "No Sound" pop-up button shown in the picture at right lets you choose an audio input to record from if your video input isn't muxed.
- The "Play-thru" pop-up button lets you choose an audio output to play the inspected digitizer's audio stream through.
- The "Volume" slider and "Mute" button adjust the audio of the digitizer.
Windows from other applications as Video Inputs
Syphon is great, but a lot of applications don't support it yet- so this feature in VDMX is one way to get video out of apps that don't support Syphon. This will list every visible window (if a window is hidden or in the dock, it's not listed) with a title on your system. If a window you want to use *isn't* visible, make sure it has a valid title. Window video sources will work even if the windows are covered up by other applications, so you don't need to worry about setting aside unobstructed space onscreen for the window you want to use: it can be behind VDMX and still work. The main drawback to this approach is that it's not as fast as Syphon- the OS X window manager has to make an additional copy of the contents of the output window in RAM, then push it to your GPU- which can take a while (especially if you have an old GPU/computer/if you're working with large windows). A side-effect of this is that if the window is redrawing very rapidly or at an unusual framerate, you may see flickering or tearing- which can be adjusted by changing the framerate of the window input. Regardless, this approach is extremely useful for quickly letting you pull video from other software.
Like video digitizers, clicking on a window input inspects it and lets you set a couple basic options:
- "Crop" lets you specify a crop rectangle for the video input as expressed by pixels from the left/top/right/bottom side of the frame. This is useful to crop out scroll bars, title bars, and other unwanted portions of the window.
- "FPS" lets you set the rate at which VDMX tries to get new images of the inspected window from OS X's window manager. The higher the FPS, the more data you're copying and pushing to your GPU. If you see flickering, you should make sure the FPS field is an even multiple of the refresh rate of the display your window's on.
- "Limit Size?"- if enabled- limits the size of the window input to the specified resolution. By default, this is enabled and window inputs are limited to VGA-res (640x480). The higher the resolution, the more data you're copying and pushing to your GPU.
Layer Source Controls by Media Type
Depending on the type of clip is playing on a layer, the layer source window will show a different set of UI controls for working with that specific media type.
- "Time Slider" Shows the name of the currently playing movie and the current time in seconds. Click or sync to a data-source to jump to a different point in the movie timeline. The min and max range handles can be used to set the in and out points of the movie.
- "Set" buttons will adjust the in or out loop-point of the movie to the current movie position.
- "Reset" buttons are available for changing the in and out loop-points of the movie to the beginning and end points respectively.
- "Pause" toggle button (= or > depending on the state) can be used to start and resume playback without adjusting the playback rate.
- "Rate" slider sets the direction and speed at which the movie plays back.
- "Reverse" toggle button (--> or <--) allows for changing the direction of playback without changing the speed.
- "Q" toggle enables and disables rate quantization. When active the playback rate of the movie at 1x will be stretched or compressed to match the number of measures specified relative to the currently selected clock. If the BPM of the clock changes, the speed of the movie will change by the same percentage.
- "Sync" button jumps the movie time to match the current measure time of the selected clock when quantization is active.
- "Clock" pop-up menu sets the Clock plugin instance that the layer should sync with when quantization is active.
- "M" text field sets duration of the movie in measures, used along with the BPM to determine the playback rate of the movie when quantization is active.
- "Back" and "Fwd" buttons cause the time slider to jump backwards and forwards in time relative to the current movie time.
- "Jump By" slider and "Jump By Units" pop-up menu set how far backwards or forwards the movie will jump when the back / fwd buttons are used. Units can be set to Seconds, Frames, or Beats. When using Beats the jump time will be relative to the currently selected clocks BPM.
- "Scratch" slider can be used to slide the movie time backwards or forwards relative to the current movie time. When using a mouse click with this particular slider you can drag infinitely left or right. Data-sources can only scrub within a limited range so it is often useful to switch receivers on and off via slider presets.
- "Loop Behavior" pop-up menu sets what happens when the movie time reaches the in or out point boundary. Can be set to cut-to black on end, hold on last frame, loop, or reversing loop.
- "Volume" slider adjusts the overall loudness of the movie.
- "Mute" toggle button switches sound output on and off without adjusting the volume.
- "Audio Device" pop-up menu sets which interface is used for sound output. The <Default Audio> will use the device specified in the VDMX preferences.
- "Audio Channels" pop-up menu sets which stereo output channels are used by the layer for sound playback when using an audio interface that supports multiple channel outputs.
Video Generators: CoreImage, Quartz Composer, FreeFrame and Flash
For source types that have custom pre-defined input parameters VDMX will automatically create a user interface with the appropriate controls for each setting. Like with the control surface plugin, the layout for these interfaces can be customized by clicking the additional "Inspect" button in the layer source window.
Additionally a Section Preset UI control is available for saving and restoring different sets of values and states of each individual UI item.
Some common examples of how parameters are mapped to UI items include:
- Numbers -> Sliders
- Booleans -> Buttons
- Integers / Indexes -> Pop-up Menu
- Colors -> Color Picker
- 2D Point -> 2D Point UI
- Images -> Pop-up Menu with list of available video senders in VDMX
Text layers are similar to video generators, with a few additional UI items. Below these special controls will appear any additional parameters specific to the special handler patches that are being used to convert the text strings into video.
- "Text Source Composition" pop-up menu chooses which patch should be used to render the text for output. These Quartz Composer patches can be found in the qcTextSources folder in the Assets directory.
- "Text Units" pop-up menu sets how the text file should be broken up- by character, word, sentence or line breaks.
- "Prev" and "Next" button changes the current output string to the previous or next chunk respectively. Note that some text styles may use their own internal playback timing that will automatically step through the text.
- "Loop Behavior" sets whether the text parsing should stop at the last chunk or repeat when finished.
- "Text Editor" is used to preview and edit the contents of the text clip. Double click on a block of text to set it as the chunk that will be displayed next.
Still images loaded on a layer by default will render with no additional controls.
Optionally, images can be passed off to a custom Quartz Composer patches for additional processing, such as zooming or resizing before being passed off to the layer FX and composition. This can be useful when working with large images whose dimensions are bigger than your canvas size. Once a custom patch is selected from the "Image Source Composition" pop-up menu additional UI items may appear that are specific to the chosen patch.
The web source type controls contain a miniature browser for interacting with and navigating between web pages.
- "URL" text field is used to enter web addresses.
- "Back" and "Fwd" move through the browser history.
- "Web Preview" is a scaled down version of how the site is rendered for output. Interact with links, text fields and other UI items via clicks.
- "Horiz" and "Vert" scroll sliders adjust the horizontal and vertical offset positions of the web page view.
Video Receivers: Live Inputs, Plugins, Layers, Window Inputs, Syphon
When a layer is set to receive video from another source, there are no additional playback controls in the layer source window.
Video Output: Display Options, Fullscreen modes, and multiple GPUs
First of all:
- Cmd-F opens the "Output Options" window.
- Cmd-Shift-F toggles fullscreen mode on and off. Once you're in fullscreen mode, you may have to use the "Output Options" window to decide which screens you want VDMX to go fullscreen across.
- If you're in fullscreen mode, pressing the Esc key will disable fullscreen on your "Main" screen (the screen with the menubar). You'll still be in fullscreen mode.
- All the output modes have various sizing modes- these work the same way as the layer size modes mentioned earlier:
- "Fit" makes the canvas as large as possible within the chosen output area without cropping the canvas or changing its aspect ratio. If the aspect ratio of your canvas doesn't match the aspect ratio of your window/fullscreened displays, you'll see letterboxing.
- "Fill" makes the canvas large enough to completely fill your window/fullscreened displays. The aspect ratio of the canvas isn't changed, so if there's a mismatch your canvas will be cropped.
- "Stretch" makes the canvas completely fill your window/fullscreened displays. If the aspect ratio of the canvas doesn't match the aspect ratio of your output area, the canvas image will be distorted to fit.
- "Copy" does a simple 1:1 pixel copy of the canvas to your window/fullscreened displays. If you need pixel-perfect image reproduction with no interpolation in your output (such as bitmap art) you may want to use this mode.
VDMX has three different output modes: "Window", "Fullscreen", and "Advanced". None of these modes affect your layers or rendering engine- once you've rendered the canvas, these output modes just determine how the resulting video is displayed on the various output devices connected to your computer.
- At the bottom of each of the output modes is a "Use this mode as default when launching" checkbox you can use to force VDMX to use a specific output mode on launch.
- "Window" is the default output mode when you first launch VDMX. The canvas is displayed in a window- click and drag on the window to move it around, click and drag in the lower-right corner to resize it. The standard sizing mode choices are available- "Fit" is the default (your canvas will be as big as possible in your window without distorting or cropping it).
- "Fullscreen" is the fastest and easiest way to make your canvas fill one or all of the displays connected to your computer- just select the displays you want VDMX to go fullscreen on, and your canvas will be displayed in the area common to all enabled displays using the selected sizing mode. This is the fastest and easiest way to split up a single big image into a bunch of smaller images on different displays.
- "Advanced" lets you create windows one by one, specify the video source you want to appear in the window (not just the canvas/main output), the dimensions you wish to use in the video source, and the sizing mode you want to use to fit them in the window. The "+" and "-" buttons in the toolbar create/delete windows- all the other properties are edited via the table view. The "Advanced" output mode isn't useful for most situations because it requires you to manually specify a substantial amount of information- but at the same time, it lets you explicitly specify a number of extremely important and otherwise unavailable options.
VDMX supports the use of multiple graphics cards seamlessly- you don't have to do anything to enable it, it just works. Ideally, the GPUs should be from the same manufacturer (there are slowdowns when sharing data between ATI/NVIDIA GPUs), but VDMX will always make a best-faith attempt to display the resulting image onscreen.
For information about using Syphon to output video, see the Syphon Output plugin.
With the exception of the built-in sources which can be directly accessed by a layer, most media files you work with will need to be imported into a project before they can be played on a layer.
Pages and Clips
Loaded media files in VDMX are organized on pages. Each page can hold any number of clips and a project can contain any number of pages. A list of the current pages in a project can be found on the left sidebar of a media bin plugin and in the Files section of the Workspace Inspector.
Each clip is a wrapper for the media that it represents as well as any custom VDMX specific settings to be used when the file is playing on a layer.
Adding Files to a Project
VDMX has its own file browser which can be used to navigate and search for media on your computer that can be played back. Local hard drives, stored favorites, recent places and built-in sources such as live inputs and Syphon sources can be accessed here.
The available search field can be used to perform Spotlight searches of your local drives. Built-in sources will also be included in the results.
The file browser can be opened from the Window menu under Browse / Import Media. Many of the options in the browser can also be accessed directly from the right+click contextual menu in the media bin.
Disk Based Files
To add files that are on a local hard drive to your project simply drag from a window in the Finder or the built-in file browser to a page view or onto a list of pages. Files can also be loaded using a standard Mac OS open dialog window by choosing "Import Media" from the File menu (⌘I).
When possible VDMX will try to automatically create new pages for imported folders, except when directly inserting onto a specific page. New pages can also be manually created and deleted using the + / - buttons.
In addition to traditional disk-based media like movies and image files VDMX can generate and receive video frames using a variety of different formats.
These sources can be either directly accessed by layers in the Layer Source window with their default settings or added to pages as clips that can be triggered like disk based media files.
Supported types include:
- CoreImage generators
- FreeFrame and FreeFrameGL generators
- Live Inputs - Web-cams, DV, HD digitizers
- Syphon - Images provided from other applications over the Syphon protocol
- Window Inputs - The contents of any window in a visible application
- Web - Display the content from any website accessed over http://
- Layers - Uses the contents of any layer or group in VDMX, before or after FX are applied.
Organizing Files within a Project
Once files are added to pages, you may want to change their order or remove them from a project.
- Moving Clips - Clips can be moved simply be selecting them in a media bin (shift+click) or list view and dragging them to a new location in VDMX. While dragging clips an insertion marker will appear when mousing over a page that can accept the drop.
- Duplicating Clips - To create a copy of a clip use the same instructions as for moving clips but also hold down on the option (⌥) key. All of the settings for the duplicated clips (such as in/out points) will be copied as well.
- Deleting Clips - To remove clips from a page, select them and press the delete key. A dialog box will appear asking to confirm the operation.
- Exporting Clips and Pages - Right+click on one or more clips or pages and choose the export option to save a file collection that includes all of the settings to disk. These collections can be loaded like any other disk based file or folder.
Triggering/Playing Back Files
See the media bin plugin for more information.
In the first tab of the Workspace Inspector you'll find the File Inspector which can be used to load, manage and edit the properties of pages and media clips in your current project.
In the top-most section of the File Inspector clicking on a page in the left column will reveal its contents on the right. From here clips can be re-ordered or moved to another page by dragging to the desired location.
By default, the contents of a page are set up manually by loading files from the Finder or media browser. In the page inspector you can specify a directory, such as a folder on disk, with which the page will keep in sync with. When active the page will attempt to create a new clip for each item in the directory.
Additionally you can set a filter for a specific file type, such as movies or still images, and whether or not VDMX should automatically delete clips that are removed from the directory.
When one or more clips are selected in the Workspace Inspector the clip sub-inspector will appear.
By default, in most cases clips will use the current source controls, FX, and composition settings of the layer it is playing on. Using the file inspector you can specify which of these settings should be overridden when the clip is triggered.
To activate a custom attribute setting for a clip, click on the toggle next to the name of the attribute in the list.
In some cases additional options for the attribute may appear.
For each listed attribute is a toggle for whether or not the clip should override or use the current layer setting. When an attribute is enabled for a clip, additional options may appear.
When a single clip is inspected, an additional sub-inspector will appear showing a preview of the output from the clip with the specified settings.
- Clip Name - The name of a clip can be changed by clicking on its name in the list view in the top file inspector. After a moment the text field will become editable.
- Source Controls Settings - The available source attributes for a clip will vary depending on the type of file.
- For generative sources such as CoreImage, Quartz Composer patches, text, FreeFrame, Flash and Web you can specify the resolution and fps of the clip, as well as the settings for any custom inputs that the patch / plugin has defined.
- For fixed sized sources, such as movies, live inputs, and video receivers, each of the built-in controls such as rate and volume can be individually overridden, as well as the render fps, but not the rendering resolution.
- When selecting multiple clips, only the attributes that are common to the selection will be editable from the inspector.
- Custom FX Chain - Create a custom FX chain that is loaded whenever the clip is triggered on to a layer.
- Composition Settings - For each clip you can override the following layer composition controls. The attribute picker lets you specify whether to override just the value, or all slider / button / pop-up menu settings.
- Blend / Composition Mode
- Size Mode
- Position Mode
- X Position
- Y Position
- Custom QC Comp Mode settings (when applicable)
- Setting a Custom Icon - When a single clip is being inspected an additional sub-inspector will appear to show a preview of the media along with any custom applied FX. The current frame of the preview can be stored as the icon for the clip by clicking the "SET ICON" button in the clip inspector.
Relinking Missing Media
When a project is opened VDMX will attempt to relocate any media files that are referenced by your clips. If the media associated with a clip has been moved, renamed or removed from the system, you may need to point the clip to the new file before it can be played back.
Clips whose media file is unavailable are indicated by a special "missing" icon in the media bin.
You can either relink clips immediately after a project is finished loaded or at any time later by choosing the Relink Missing Media or Fast Relinking options from the Workspace menu.
Using the "Relink Missing Media" panel, accessed from the Workspace menu, you can view a list of all clips that are in the missing media state and connect them to different files.
To relink a single clip select it in the list and click the Find button. For disk based files VDMX will perform a search to attempt to locate the original media for you. If no matches are found, or the list of results does not include the file you are looking for, click the 'Browse' button to reveal a standard Mac OS open file dialog window to pick a specific file to relink with, or click 'Skip' to close the window.
Using the Find All button will go through the same step for each missing clip.
If the Automatically Resolve Conflicts option is active VDMX will search the directories of any successfully relinked files for other missing files and automatically reconnect them if found.
Rather than manually browsing / searching for missing media most of the time VDMX can automatically use Spotlight to locate the files in the background without any additional user interaction. If more than one match is found VDMX may make a "best guess" based on stored meta-data about the file.
This feature can be activated from either from the missing file dialog window or using the Fast Relinking option from the Workspace menu.
The "Plugins" tab of the Workspace Inspector reveals the interface for creating, deleting, inspecting, and otherwise working with VDMX's plugins. A "plugin" is basically anything in VDMX that isn't a layer- plugins provide data sources and interface items that you can use with VDMX. To create a plugin, click on the "+" button in the toolbar below the list of plugins, and select the plugin type you want to create from the pop-up menu that appears. To delete a plugin, select the plugin in the list of plugins and click the "-" button in the toolbar. To rename a plugin, double-click on the plugin name in the list of plugins and enter a new name. To copy, paste, or duplicate plugins, click on the "sprocket" icon in the toolbar below the list of plugins.
- "Audio Analysis": analyzes an audio stream from an audio input and makes a variety of data sources available that describe the audio stream.
- "Blackmagic Output": outputs a video stream via a Blackmagic video output device.
- "Clock": a simple clock plugin that can be slaved to a MIDI clock, configured by tapping a tempo, or controlled via several other means.
- "Comm Display": displays incoming MIDI and OSC data for checking incoming data streams.
- "Control Surface": Lets you create a variety of UI items for custom use. These UI items can also be published as data sources, and thereby used to control other UI items within VDMX.
- "Cue List": Use this plugin to set up pre-planned clip triggers and locally-created data sources that occur at specific times during a performance.
- "Data Looper": records data from input devices into tracks, allows you to edit them, and then loops them back, published as data sources.
- "HID Input": publishes data sources in VDMX for the controls on a connected HID device (such as a gamepad or a joystick).
- "LFO": LFOs are low-frequency oscillators. Each LFO can have a number of waves which are highly configurable- these waves are published as data sources available to any receiver in VDMX.
- "Media Bin": The primary means of importing, organizing, and triggering media files on layers.
- "Movie Recorder": records audio and video from VDMX into QuickTime movie files.
- "Preview": Preview plugins display the video streams you're working with- and provide a number of built-in controls for working with layers and different source types.
- "Step Sequencer": Step sequencers let you sequence values of different types (integers, booleans, decimal numbers- even colors). Each step sequencer can have multiple tracks, and their values are published as data sources.
- "Sticky": A quick and easy way to leave notes for later in your workspace
- "Syphon Output": Publish any of the video streams you're working with via Syphon, making it available to other apps that support it.
- "Timecode": receives timecode (via LTC, MTC, OSC- anything), generates timecode, publishes timecode as data sources in VDMX, and publishes timecode via LTC/MTC/OSC/etc.
- "Two Channel Mixer": The quickest and easiest way to adjust the opacity of two different layers at the same time, "mixing" between them.
- "Wiimote": The fastest and easiest way to use a Wiimote with VDMX.
- "QC-based plugins": This isn't a specific plugin- this is a *category* of plugins which you can create by loading QC compositions as plugins: any published input splitters are made available as UI items in VDMX, and any published output splitters in the plugin are published as data sources of the appropriate type in VDMX.
The Audio Analysis plugin lets you take an incoming audio signal, say from a microphone or line-input, and convert it into data-sources to use as control data within VDMX or send to other applications.
For each audio analysis plugin you can specify-
- An audio source and channel to analyze
- The amount of gain to apply to the incoming sound
- Any number of frequency ranges to track (filters)
- An audio output for previewing
Like all plugins in VDMX, you can have as many copies of the audio analysis plugin as needed, each with their own custom settings.
Main Plugin Interface
Most of the options for the audio analysis can be accessed from the main plugin interface or its right+click contextual menu.
On / Off button:
In the lower left corner is a button to enable the audio analysis plugin. To save on CPU usage you may want to turn this off when it is not needed.
Signal preview and filter setup panel:
To change the position or width of a filter, click on its grab bar. To adjust the center frequency drag left and right. To adjust the frequency range drag up (wider) and down (narrower).
This slider sets the overall gain level of the incoming audio before the analysis is performed.
In some cases you can also adjust the input volume of a built-in audio device (eg. microphone, line input) on a hardware level from the System Preferences under Sound / Input. Other external devices may have their own signal gain control as well.
When the play-thru option is enabled this will also affect the loudness of the sound output.
Section Preset UI:
Below the signal preview in the main plugin window is a standard VDMX section preset control for saving and restoring arrangements of frequency filters.
The current source, play-thru and gain levels are not affected.
Input Device Menu:
Sets which audio source is used as an input for analysis. Choose a specific device or the system default as set in the System Preferences.
Sets which channel of audio from the incoming signal is used as the input for analysis. Can bet set to a single specific channel or a summation of all incoming channels in the signal.
Sets the output destination for previewing the incoming sound.
In the filter manager you can add, remove and give custom names to your analysis filters.
Clicking on a filter in the list will reveal a sub-inspector for configuring data-receivers for adjusting the center frequency, range, gain and smoothing level for each individual filter.
The Blackmagic Output plugin lets you send any video source in VDMX out any Blackmagic video hardware connected to your machine. A single plugin can publish one video source out output.
- The "Video Source" pop-up button lets you select which video source you'd like to publish.
- The "Black" button lets you quickly black out the output.
- The "Crop Video Src" interface lets you crop the chosen video source before publishing it.
- The "Output Device" pop-up button lets you select which device you want to send the video out of. Please note that the output you want to use on that device- for example HDMI vs. SDI- is selected in the System Preferences on your machine (not in VDMX).
- The "Output Format" pop-up button contains a list of resolutions and output frequencies supported by the selected device- as soon as you select a viable output format, VDMX will begin publishing the video.
Since VDMX is frequently used to create performance setups for accompanying musicians, many aspects of it benefit from the ability to be synchronized to a central clock. The clock plugin is how you accomplish this in VDMX- other plugins that offer timing and quantization options (for example, triggering a clip on the nearest quantized beat) can simply present the user with a list of potential clock plugins to choose from.
- A Clock plugin can be in one of three different modes- it can either be generating the clock internally, it can be slaved to a MIDI clock signal you're receiving, or it can be using Waveclock to automatically detect the BPM from an audio source. You select which mode by using the "Mode:" pop-up button in the clock's inspector.
- "Internal" mode generates a clock signal internally- this is the default state for a newly-created clock plugin. In this mode, you can enter the BPM manually by using the "BPM" text field in the plugin window, or clicking/triggering the "Tap" button on each down beat. The "/2" and "*2" buttons in the plugin window halve or double the BPM, and the up and down arrow buttons increase/decrease the BPM gradually.
- "MIDI Slave" mode slaves the clock to a MIDI clock signal sent to the destination you choose.
- "Waveclock" is an extremely accurate beat tracker by Wavesum that can accurately detect the BPM of an audio input on your machine- you select which audio input you want to analyze in its submenu (by default, the default audio input defined in your System Preferences will be analyzed). This mode is so useful that there's a button in the plugin window to enable it (the button has a speaker and a clock icon on it). If you want to select a different audio source- or adjust the gain or silence threshold- you can do so in the clock inspector.
- The "→|" button skips the clock forward to the next downbeat and restarts the measure. This works with every clock mode.
- The "↩" button resets the measure and time count of the clock and restarts the clock. This works with every clock mode.
- The "BPM" text field will always display the BPM of the mode being used- it can also be used to set the BPM if the clock is in "Internal" mode. If you would prefer to enter the duration of the measure in seconds, you can do so by inspecting the plugin, and using the "Display:" pop-up button to select "Seconds".
- In addition to being available to plugin-specific timing and quantization options, the clock plugin also publishes several data sources which can be used by any receiver- there are a variety of data sources, including for individual beats, every downbeat, every couple bars, etc. The "Beats" and "Divisions" fields in the clock's inspector determine how many beats per measure and how many subdivisions per beat, respectively.
- The clock plugin has a section preset UI item- this saves/restores the contents of this plugin and this plugin alone.
The Comm Display plugin displays any MIDI and OSC data received by VDMX and is useful for checking and debugging the data streams you're receiving. There are only three controls: the "Type" pop-up button for choosing MIDI or OSC data to display, a "Pause" toggle which pauses (disables) the display of new input, and a "Clear" button. If you're not explicitly using a Comm Display plugin you should either pause or delete it to avoid wasting resources- this plugin was created as an aid in debugging OSC and MIDI data received by other applications (particularly OSC data, which may be received as lists of arbitrary values depending on the software sending it).
Use this plugin to set up pre-planned clip triggers and changes to locally-created data sources that occur at specific times during a performance. It has an assortment of timing control options (index/beats/measures/seconds/SMPTE), and can play back on its own or synchronized with other systems using internal (clock and timecode plugins) or external (MIDI, OSC, DMX, MTC, and LTC) data sources. Cues can also be exported and imported to a simple CSV document for collaboration or use in other projects.
Main Cue List View
The main interface for the Cue List contains the controls for configuring and playing back actions for the plugin to execute at the specified times.
1. Editing Cues
A list view showing all of the current cues fills most of main plugin interface. Each row in the list represents a single action that happens when the specified time is reached.
- "Jump Button'" To jump to a specific cue, click the button in the left-most column. From the UI Inspector you can assign data-sources to trigger this button.
- "Time'" column is used to set when an action takes place. Click in this text area to type in a new value for any row.
- "Target'" column is used to set what kind of action takes place at the time for this cue. From the pop-up menu you can choose between changing the value of a data-source or selecting a layer that will have a clip triggered to it. Data-source targets can be added, removed and configured from the plugin inspector.
- "Value'" column is used to set the media that will be triggered to a layer or the value that published by a data-source to control parameters. This field will update to the appropriate type for number entry (float or index), color selection (color), on/off switch (boolean), text field (string), or a clip selection menu for layers.
- "Title" column allows for including an optional display name for each cue.
- "Enabled" column can be used to turn cues off without deleting them from your list.
- "Lock" column can be used to prevent changes from being made to individual cues.
Below this view are buttons to add ("+") and remove ("-") cues from the list. In the sprocket menu you’ll find additional useful features for grouping cues,
When editing row items in the Cue List, there are several options that are available by right-click or from the sprocket options menu. These include the ability to quickly expand / collapse all groups, change the enable or locked state of selected cues and creating new groups by selection.
Additionally for fast editing and entry of cues, the following keyboard shortcuts are available:
- ⌘-enter – create new cue at selected time
- shift-enter – jump time to the selected cue
- shift-left – decrement the time of selected cues by one minor time unit
- shift-right – increment the time of selected cues by one minor time unit
Tip: Each row also contains a boolean receiver which can be used to jump to the specified cue. When a row is selected in the cue list, the UI Inspector will update to show the settings for its boolean receiver.
Tip: The format for the “Time” column can be changed from the plugin inspector to be represented as indexes, beats, measures, SMPTE or seconds. From the inspector you can also specify the appropriate frame rate or musical time signature that you would like to work with.
2. Cue List Time Controls
Along the top of the Cue List is a standard Section Preset bar which can be used to save and restore different states for an instance of the plugin. These presets will change all of the cues, data-sources, controls and other options.
Next are the time controls, which include:
- "Time Slider" Use this to jump the playback position to a different time.
- "Cue Name / Time Display" Text labels that show the title and time at the current play position. Can be configured from the options panel to display as countdown to next cue, time within current cue, total time remaining and current elapsed time.
- "Restart Button" Jumps to the first cue. If using a time code or clock plugin to drive the plugin this will resync with the appropriate time.
- "Previous Cue Button" Jumps to the previous enabled cue.
- "Pause Button" Pauses the advancement of time.
- "Next Cue Button" Jumps to the next enabled cue.
- "Random Cue Button" The ? button jumps to a random enabled cue.
Cue List Inspector
The Cue List plugin can be customized in several ways using the inspector panel. The settings are arranged in 4 inspector panels.
1. Cue List Data-Sources
Each Cue List can publish any number of data-sources to control parameters in your project. The main data types of "float", "index", "boolean", "event", "color" and "string" are available.
Each data-source that is configured in the inspector shows up as an option in the pop-up menu for the target column in the main Cue List interface.
For applicable data-types, such as float numbers and indexes, you can specify how the published values should change as they go from cue to cue using the "Interpolation" column. The default setting is to "Jump" between values but for smoother transitions you can specify "Linear", "Smooth In", "Smooth Out" or "Smooth In and Out".
In addition to using these values internally, for each data-source that is configured for a Cue List you can also specify any number of Data-Senders for output over DMX, MIDI or OSC by using the Cue Value Data Source sub-inspector. Click on a data-source to see the sub-inspector for configuring these senders. See the section on Data-Senders for more information on configuring individual senders.
2. Cue List Navigation
From this tab in the Cue List inspector you can configure data-receivers for jumping to different cues directly based on their index or their name:
- "Jump to Cue By Index": Expects a counting number ranged 0 to the number of cues available.
- "Jump to Cue By Float": Expects a normalized number ranged 0 to 1 and scales to the number of cues available.
- "Jump to Cue By String": Jumps to the first cue where the title field matches the provided string.
To jump to specific times, or to sync the time to a specific data-value, use the Time Slider in the main Cue List interface.
3. Cue List Time Settings
The formatting for the time column in the Cue List plugin can be set to several different modes to make it easier to work in different work environments:
- "Index mode": Cues times are displayed as increasing counting numbers starting at 1.
- "Measures": Enter times in clock notation, measure:beats:sub-beats. Requires entering a BPM to determine rate.
- "Beats": Enter time in number of beats. Requires entering a BPM to determine rate.
- "SMPTE": Enter time in standard SMPTE format. Allows for specifying number of frames per second.
- "Seconds": Enter time values in seconds.
Depending on the use case, the Cue List contains several options for the behavior for playback and editing of cues.
- "Start Time": For situations where time code does not start at 0, the Start Time option can be used to specify a different point to begin playback. When adjusting this setting you will be presented with an option to automatically shift existing cues to the new time offset.
- "Loop Playback": Sets whether nor not the Cue List should pause or restart from the beginning when it reaches its last cue.
- "Auto Update Time Slider Marks": When enabled, interesting marks on the time slider in the main interface will automatically update to match the times of cues.
Syncing time from other plugins: Each Cue List plugin can be set to update its time in sync with a "Clock or" "Timecode" plugin. From the pop-up menu in the inspector, select a plugin by name to receive its time values.
When receiving clock or timecode, the time offset text field can be used to add or subtract a specify amount before applying as the current time.
The "lock to source'" option can be used to force the time to stay in full sync with selected plugin time. When this option is enabled, the time slider and other time navigation controls become inactive.
4. Other Cue List Options
- "Time Display'": Set the display in the main interface between showing the Current Time, Cue Start, Cue Time, Next Cue Time, Time To Next Cue, or the Total Time Remaining.
- "Clip Display'": Switch between showing triggers to layer as thumbnails or names.
- "Auto Scroll Cue List'": During cue playback, automatically adjusts the scroll position of the main interface to include the currently active cue.
- "Preload Media'": When enabled, media references from clips will be preloaded for faster triggering.
- "Publish Colors RGB / Publish Colors HSV": In addition to publishing each color data-source as a ‘color’ data-type, these toggles can be used to publish the individual RGB / HSV channels of the color as individual data-sources.
- "Import / Export As CSV:'" The data from a cue list can be exported into a CSV formatted document that can be reused in other VDMX projects or edited in most popular spreadsheet software. To create a CSV file for your cues, click the "Export CSV" button in the options panel of the Cue List plugin. CSV formatted cue data can be loaded into a plugin by clicking the "Import CSV" button.
The Data Looper plugin lets you create tracks that record data (values) from a data source, and then loop that data back, publishing it to the track's data source. Recording and playback is always quantized to the chosen clock, and the plugin also has a built-in editor that allows for quick and extensive modification of the recorded data, including scaling, warping, translation, and deletion.
- Playback and recording is track-based: a single plugin can have multiple tracks. Each track's value is published as a data source in VDMX. You can choose this data source using any of the usual means, or by ctrl-click-dragging from the track preview (or the track editor) to any UI item.
- All tracks in a plugin are quantized to the same clock, which is selected by the pop-up button in the top-right of the plugin window. This means that all recording and playback is quantized- as long as your clock is in sync with the real world, everything you record and loop will also be in sync.
- The Data Looper plugin has two basic interfaces- the "View All" interface, and a track editor interface. You switch between these by choosing which track you want to view (either you "View All", or you select a track to edit).
The "View All" Interface
The "View All" interface displays an thumbnail preview and basic controls for every track in the plugin. Each track has its own set of controls for recording and playing back data, which are visible in this view- there's a pop-up button for changing the track's mode, and a value slider which is used by many of the modes.
Every track has a "mode"- this mode determines what the track is doing at any given point of time.
- "Solo" doesn't play back or record anything- if you're soloing, the track's data source value comes directly from the value slider. This mode offers a way to immediately get manual control over a track data source's value.
- "Rec(New)" deletes the existing track data and starts recording from the value slider. If you want to make a new loop, this is what you select.
- "Rec(Add)" will play back the track once (or continue to play it back if it's already playing back), and then as soon as the track finishes playing back it begins recording new data from the value slider.
- "Rec(Over)" immediately starts recording from the value slider over the existing track data. The track doesn't get any longer- it just keeps re-recording over the same duration indefinitely until you tell it to stop.
- "Play" loops whatever data you've recorded. Clicking on the preview will jump playback to the nearest quantized location, but aside from that there are no playback controls to speak of- it's just going to keep looping the data quantized to the selected clock.
- "Play once then solo" plays the track data a single time, and then immediately switches the mode to "Solo". If you want to "trigger" a track to play it back once and then switch to manual control over the data source value, this is how you do it.
The preview of the wave in the "View All" interface shows where playback is within the track (or how much data you've recorded, depending on the mode).
- Clicking on this preview will jump playback to the quantized location nearest your click
- Double-clicking on the preview will automatically start editing the track data
- ctrl-click-drag from the preview to any UI item to assign it that track's data source.
- Right-clicking on the preview will open a contextual menu with a number of options for copying, pasting, and deleting the track.
The Track Editor
The track editor interface allows you to make chronological modifications to the track's data. You can switch to the editor UI by either double-clicking on a preview in "View All" or selecting a specific track from the plugin's pop-up button.
- The editor has its own "mode" pop-up button and value slider. The pop-up button and val slider from the track still work- this is an extra, dedicated set of controls that will always control whatever track is currently displayed in the editor.
- The editor has limited support for undo/redo- while you're in the editor, any changes you make to the wave can be "un-done" as expected.
- The "main" editor area has three basic sections- there's a small strip along the bottom that can be used to change the duration of the track. This automatically quantizes edits to the nearest full measure.
- Along the top of the editor is another strip- this strip lets you create or reposition warp points. Warp points are temporary markers that are used to distort or rearrange the data in a track. You click in the strip to make a warp point, and if you want to reposition a warp point you just click and drag it around. Warp points can be deleted by "tearing them off" the strip.
- The majority of the editor is taken up by a preview of the data you recorded. if you click on a warp marker in this area and drag it, the data on either side of it will be distorted. you can also click and drag on the space between warp points to slide it around, and rearrange the track data. if you hold down option while you click and drag, you'll copy the data before moving it.
- ctrl-click-drag from the editor to any UI item to assign it that track's data source.
- Right-click on the editor for a contextual menu with a number of options for copying and pasting track data.
- At present, there's no way to modify the track values- we experimented with this both manually (clicking & dragging to "draw" track data) and procedurally (like "erode", "noise", etc), but chose not to include this because during testing it was almost always faster and easier and the results were typically more in line with what was desired when simply re-recording the track. This is something we're open to re-visiting later, so if you have any strong opinions let us know!
The Data Looper Inspector
The Data Looper Inspector allows you to set a number of options that affect recording and editing behavior:
- "Start recording on next measure" is an option that comes into play with the "record new" mode. If enabled, recording won't start until the beginning of the "next measure"- this option is useful because it gives you an opportunity to "lead in" to the changes, which often produces a better output loop without editing.
- "Continue recording through measure end" is another option that can be used to help produce smoother loops. If enabled, this option will ensure that the track continues recording through the end of the current measure.
- "Snap warp points to peaks/troughs" does exactly what it sounds like- if enabled, warp points you drag around in the editor will snap to local peaks/troughs in the track's data.
- "Crop last measure if < XXX measures" will automatically crop the last measure you recorded if its duration is less than the provided value. This is enabled by default, and the goal here is to minimize the "cleanup" you have to do on your track: if you stop recording a little bit late then this option will automatically toss out the "extra" data you recorded.
The inspector also has some options for setting the global track mode default options. By default, the "mode" pop-up button for each track is created with a number of section presets for the modes we used most frequently while developing and playing with this plugin. These are the standard per-item presets, so they can be customized extensively by inspecting the pop-up button. You can also change the default presets that are created when you make a new track by using the checkboxes in the inspector.
The HID Input plugin allows you to work with the devices such as gamepad, joysticks, controllers, etc that are compatible with the HID protocol. The UI is minimal- the plugin itself just has a pop-up button used to select an HID device. When you pick a device, the plugin will automatically create data sources for the available controls. The plugin's inspector displays a list of the control, and allows you to calibrate their min/max ranges. Button-type inputs in HID plugins can be used with "Detect" mode when setting up receivers (you can enable "Detect", then press a button on your HID device, and the assignment will automatically be created).
The LFO plugin, or low-frequency oscillator, generates control signals using built-in function generators (sine, cosine, random, etc.) and custom bezier curves.
For each LFO plugin you can specify:
- Any number of waveforms to evaluate
- The nominal duration over which the waveforms are evaluated in seconds or measures
- Standard transport controls- time scrub, pause, relative rate adjustment, loop-mode, reverse and jump-time
- A clock plugin to use as an external timer
- Options for the waveform record mode
Additionally for each waveform you can set:
- The published data-source name
- Multiple sub-waveforms, each with their own type, to create complex piece-wise functions
- Control points for bezier curves and adjusting function generator frequency / amplitude
- A data-source that the waveform will use to create a new bezier curve when record mode is active
- Whether or not the waveform is visible in the curve editor
Main Plugin Interface
Edit waveform in UI inspector - click on curve
Move node point - click and drag on the node
Add new point to selected curve - opt+click at new point location
Reveal control point for a node - cmd+drag on the node
Hide control point for a node - cmd+click on node or control point
Create / Duplicate waveform - right+click menu
Delete waveform - right+click menu
Set the duration over which the LFO will evaluate its waveforms when playing at a rate of 1x. When using an external clock plugin the units of measurement are bars, when using the internal LFO clock it will appear in seconds.
Level Indicator: Shows the current level of each waveform. Click on a column to select/inspect a curve.
Rate, time, loop-mode, reverse direction, pause and jump-time.
Toggle this button on to beging recording new bezier curves for waveforms enabled for record in the LFO inspector.
The LFO will record for the specified duration regardless of the current 'rate' settings and automatically stop.
Section Preset UI:
Below the curve editor in the main plugin window is a standard VDMX section preset control for saving and restoring arrangements of waveforms.
The current transport control settings are not affected.
LFO Inspector Options
Set a clock plugin that the LFO should keep in sync with. When using an external clock the unit of length of the LFO switches from being in seconds to measures.
Add, remove, rename and change the record settings for individual waveforms.
Set the number of column divisions, sub-divisions and row dividers for the waveform editor display.
LFO Waveform Inspector
When an individual waveform is selected in an LFO it will become inspected in the UI Inspector window. From this control panel you can manually enter in the positions of each node and control point, as well as the function type for your custom curves.
Within a single waveform you can mix different function types to create complex piecewise functions.
In the main interface for the media bin plugin the clips on the currently selected page can be loaded, browsed, organized and triggered to layers.
The currently viewed page can be set either using the Page Menu at the top-right of the media bin or by clicking on the page in the Table of Contents list.
The page viewer has a number of useful features for working with clips and pages:
- Loading and Organizing Media Files - See the "Adding Files to a Project" for details on how to import media and perform common organizational tasks like moving and copying clips.
- Filtering - To filter the contents of the current page use the search field at the top of the media bin. Only files whose name or meta data match the entered terms will appear in the results.
- Sorting Clips - Using the right+click contextual menu you can re-order the contents of a page based on the file name or by file path (groups clips by their location).
- Adding Pages - New pages can be created by clicking the + button (new empty page) or by dragging a selection of files (either from the file browser, the Finder or a page viewer in VDMX) into the Table of Contents. The order of existing pages can be changed by dragging within the list.
- Renaming Pages - Double click on their name in the list and typing in a new name. Pages must have unique names.
- Removing Pages - Clicking the - button will delete any pages selected in the list.
By default all pages are displayed in the Page Menu. This can be customized in the Menus section of the media bin options inspector.
Once media files are added to a project they can be played back on layers. The media bin can be configured to trigger media using a variety of different hardware controllers or automated behaviors from within VDMX.
- Mouse Click - Clicking on a cell in the media bin will trigger the clip on the target layer.
- Keyboard, MIDI, OSC, DMX and other data-sources - In the first tab of the media bin options inspector is for setting up shortcuts for triggering clips with hardware controllers or VDMX's internal data-sources.
- To add a new receiver click the + button.
- To assign a hardware shortcut, select the row of the desired receiver, clicking the detect button and sending a keyboard / MIDI / OSC / DMX message to VDMX.
- The detect range option can be used to quickly set up multiple MIDI or OSC shortcuts by sending only the first and last note values.
- The shortcut also can be set to a specific data-source using the receiver list menu.
- Shortcuts can be removed using the - button or by using the Clear All button.
By default triggering a clip, whether by mouse click or a shortcut / data-source, it will begin playing back immediately on the target layer and continue to play until a new clip is triggered or the file is ejected from the layer.
The media bin plugin has several other trigger modes and options that can be used to customize the behavior of how clips are triggered.
- Voice Mode - Set the behavior for how the next target layer is determined when new triggers are received.
- Monophonic (Default) - No automatic changing of the target layer when clips are triggered. Target layer can be manually changed using the Layers menu.
- Cycle - Each time a clip is triggered the Layers menu in the bin will automatically advance to the next menu item as specified in the Menus section of the Media Bin inspector tab.
- Polyphonic - Triggers are sent to the next available layer based on the order specified in the Menus section of the Media Bin inspector tab.
- Auto-Ejecting - Options for stopping playback on a layer.
- Note Offs - When the specified shortcut receives its applicable "off" message the clip it most recently triggered will immediately be ejected.
- Empty File - When a trigger is received for an empty cell an eject message will be sent to the target layer.
- Adjusting Transpose - In the Control tab of the Media Browser inspector are three options for adjusting the transpose (offset) of the trigger receivers in the page viewer.
- Transpose Up - Increase the offset by the number of trigger receivers (row down).
- Transpose Down - Decrease the offset by the number of trigger receivers (row up).
- Set Transpose by Index - Send an integer (non-normalized) OSC, DMX, or data-source value to set the offset to a specific value.
- Play Next, Previous, and Random Clip - In the main media bin plugin window are two buttons that can be used to step backwards (<) or forwards (>) through a page one clip at a time instead of triggering specific clips via shortcuts or mouse click. A third button is available for triggering a random (?) clip in the page viewer.
- Trigger Clip by Index On Page - In the Control tab of the Media Browser inspector are two options for triggering files based on their position on the current page.
- Trigger by Index - Receives a non-normalized integer from OSC or VDMX data-source and triggers the clip at the specified index in the page viewer. When receiving from a DMX channel this will trigger clips in the index range 0-255. When receiving MIDI the clips index range is 0-127.
- Trigger by Float - Receives a normalized (0 to 1) value from OSC or VDMX data-source and scales it to the range of the current number of clips in the page viewer, then triggers the clip at the resulting index. When receiving DMX or MIDI the range is automatically normalized to the range 0-1.
- Quantized Triggering - Using the menu next to the "T" in the main Media Bin interface you can select several different modes to quantize media triggers. The options for this setting include Immediately (no quantization), Movie End, Next On Movie End, Random On Movie End, and a Manual option. When the trigger option in the bin is switched from Immediately to Manual mode an extra button will appear in the media bin interface. In this mode any clip triggers for a layer are placed in queue until the button is clicked or banged by a data-receiver / shortcut.
Setting the Target Layer
The Layer Menu at the top left of the media bin sets which layer will begin playing back the next triggered clip.
By default all non-group layers are displayed in the Layers Menu. This can be customized in the Menus section of the media bin options inspector.
Echoing Triggers over MIDI and OSC and DMX
- Basic Sender - Using the table in the Sending section of the Media Bin inspector you can set up MIDI and OSC destinations to echo trigger messages to.
- MIDI - Sends the index of the triggered clip, starting at 0, up to 127.
- DMX - Sends the index of the triggered clip, starting at 0, up to 255.
- When sending to an OSC destination you can choose between the following data types:
- Float - Scales the index of the triggered clip to a 0 to 1 range and sends it as a float
- Int - Sends the non-normalized index of the triggered clip as an integer
- String - Sends the unique internal VDMX address of the clip.
- Hardware Device Sync - For each trigger receiver specified for the bin the state of the clip associated with the receiver will be sent back to the same address on the specified hardware controller.
When using device sync and additional inspector panel will appear where you can set what messages are sent for each of the possible states. The settings will vary from device to device and there is a lot of room for customizing the look and feel of newer controllers that can light up in multiple colors.
The possible clip states are:
- Empty / Missing - No clip is matched with the trigger in the page viewer, or the media is unavailable.
- Available - The media for the clip is ready but not playing on any layers.
- In Queue - The clip is waiting to be triggered on one or more layers.
- Playing - The clip is playing on one or more layers, but not the current target layer.
- Playing on Target Layer - The clip is playing on the target layer.
Other Bin Settings
- Preload Media - When applicable tells clips to prepare their media for playback. In some situations this can reduce the latency when triggering but can use up a lot of system resources.
- Thumbnail Mode - Adjust how clips are displayed in the page viewer.
- Icons Only
- Names Only
- Icons and Names
- Display Shortcut Paths - Hide or show the shortcut text from the trigger overlay.
- Aspect Ratio - Set the aspect ratio of the icons in the page viewer.
- Number of Columns -
- Auto Size - The number of columns will be automatically determined based on the number of shortcuts and the width of the page view.
- Fixed - Set the number of columns to a specific value.
The "Movie Recorder" plugin lets you record audio and video generated by VDMX to QuickTime movie files that can be played back later.
- The "Video Source:" pop-up button lets you choose the video source you want to record
- The "Audio Source:" pop-up button lets you choose the audio source you want to record. If this button is disabled, you need to inspect the plugin and enable audio recording.
- The "Add to page:" pop-up button lets you designate the page in your VDMX workspace the recorded files will automatically be appended to. If this button is disabled, inspect the plugin and enable "Import recorded clips?"
- The "Quantize Rec.?" toggle lets you toggle quantized recording on and off- if it's enabled, quantized recording will delay the beginning (or ending) of recording until a specific time. When you enable this, a momentary button will appear next to it ("Now"): this button is used to quantize your recording- any recordings you try to start/stop will be held until the "Now" button is triggered. You can control exactly what events you want to use to quantize your recordings by syncing the "Now" button to anything you want. The most common use of this functionality is to automatically start and stop recording exactly at the beginning of a measure- to do this, you would enable quantized triggering, and then sync the "Now" button that appears in the plugin window to "Beat 01" of your Clock plugin.
- The status of the movie recorder plugin is displayed between the "Quantize Rec.?" and "Record..." buttons
- The "Record..." buttons let you start/top video recording and record still images from the selected A/V streams.
The Movie Recorder has a number of options which are visible in its inspector:
- The "Video Codec:" pop-up button displays the codecs the plugin can record to.
- The "Record Alpha?" toggle lets you decide whether to record the alpha channel being generated by VDMX, or to ignore it and record the video stream with a full alpha channel. If this button is disabled, it's because the selected codec doesn't support alpha channels (ProRes4444, Hap Alpha, and HapQ Alpha all support alpha channels).
- The "Quality?" pop-up button lets you select the encode quality. This is a per-codec option- some codecs support it, others do not.
- The "Throttle FPS?" toggle and accompanying number field let you decide whether to throttle the recording or not, and what FPS to throttle it to if you're doing so. If you aren't throttling the recording, frames will be recorded at whatever the native framerate of your source video stream is- this can vary widely depending on the source of the video and its native framerate (for example, some webcams only average about 24fps, while recordings of the "Main Output" will likely be 50-60fps).
- The "Record at native resolution?" toggle and accompanying number fields let you decide whether or not the recording should be the native size of your source video stream, and what size it should be saved as if you elect to resize it.
- The "Record Audio?" toggle lets you decide whether or not audio should be recorded. The "Audio Codec:" pop-up button immediately below it lets you decide what codec to record to (linear PCM, AAC, or apple lossless).
- "Import recorded clips?" lets you determine whether or not the clips and pictures you record should be automatically added to your VDMX workspace.
- If "Import with empty FX chains" is enabled, the clips that are automatically imported have empty FX chains- when you trigger them, they will clear out any FX on that layer.
- If "Quantize imported clips?" is enabled, the clips that are automatically imported with quantized playback enabled- the quantized duration of the created clips is also automatically set based on the current BPM.
- If "Workspace Presets won't start/stop" is enabled, workspace presets that are triggered won't start or stop recording.
- The checkbox labelled "Custom export location" and accompanying text field allow you to specify where the files created by this plugin should be saved. By default, files you create with the movie recorder plugin will be created in the location described in the "Recording" section of VDMX's preferences- this checkbox allows you to save the files in a different, per-plugin location.
The "Preview" plugin lets you preview- and to a limited extent, interact with- the video sources you're working with in VDMX. These video sources could be coming from anywhere- a digitizer or window in another application enabled from the video inputs section of the Workspace Inspector, a layer (pre- or post-fx), another application publishing video via Syphon, etc.
- The pop-up button in the top-left corner of the plugin (it says "10" by default) is the approximate framerate of the preview plugin as measured in frames per second- the FPS of the preview plugin will not exceed this value. Under heavy loads, you can reduce this value to eke a bit more performance out of your setup.
- Immediately to its right is a pop-up button with a list of the available video sources. Selecting a video source from this list previews that video source. You could probably say that this is the "main" control for this plugin.
- If you select a layer from the list of available video sources, two additional controls appear: a pop-up button in the top right corner that lets you adjust the composition mode of the previewed layer, and a slider below it that lets you control the previewed layer's opacity slider.
If you inspect a preview window, its options panel becomse visible and provide a number of options that let you use the preview image itself as an interface item:
- If "Show size & FPS of previewed source" is enabled, the resolution and framerate of the previewed video stream is displayed in the bottom-left corner of the preview window.
- If "Jog/Scratch" is enabled, clicking and dragging in the top half of the preview window jogs the clip (changes its speed) and clicking and dragging in the bottom half of the preview window scratches the clip.
- If "Pass mouse events to previewed web source" is enabled and the preview window is displaying a layer using a web source, and clicks and drags in the preview window are passed on to your web source.
- If "Pass mouse events to previewed QC composition" is enabled, any clicking and dragging you do on the preview window is passed to your QC composition, letting you interact with it directly as if you were in the QC editor.
- If "Pass mouse events to QCFX in previewed layer" is enabled, any clicking and dragging you do on the previewed window is passed to every QCFX in the previewed layer's FX chain. If you have FX that would benefit from direct mouse interaction, this option's for you.
- If "Pass mouse events to previewed ISF composition" is enabled, any clicking and dragging you do on the preview window is passed to your ISF composition.
- If "Pass mouse events to ISF FX in previewed layer" is enabled, any clicking and dragging you do on the previewed window is passed to every ISF FX in the previewed layer's FX chain. If you have FX that would benefit from direct mouse interaction, this option's for you.
- "Clicks & changes to this previewed layer select the tab of the previewed layer" is self-explanatory: this is a good way to let you use preview windows to quickly show and hide relevant portions of your UI.
- The Preview Window Options has a pop-up button with a list of media bins- you can select a bin from this list, and clicks on the preview or changes to its target layer will also change the target layer of the selected media bin.
- The "Resize window to match aspect ratio" button resizes the preview window vertically to match the aspect ratio of the previewed video stream.
The "Step Sequencer" plugin is a control data generator where each track is set to a specific value at each 'step' in the timeline.
This plugin can be configured in a variety of ways, such as a router for switching between other data-sources (by using the column receivers for a track).
Each sequence can contain any number of data-tracks that are kept in time together.
Tracks can be added, removed or otherwise modified in the Tracks section of the options inspector.
The editor view displays the track currently selected in the track picker menu:
- The published value at each step in the sequence can be set by clicking on the column you wish to modify.
- To skip over a step in a track click on the column while holding the cmd key. The column will become grayed out until cmd+clicked again.
- Overview Mode - When a sequencer has more than one track an additional view option is available which displays all of the tracks stacked vertically. In this mode tracks can still be edited.
The amount of time over which the sequence plays once when at a nominal rate of 1x can be using the number entry field in the sequencer transport controls.
- Seconds Mode - Set the duration to a fixed number of seconds.
- Clock Mode - Specify the duration in terms of measures relative to the BPM to a clock plugin. Pick a clock from the menu and click the Q button to turn clock mode on.
In the options inspector for the sequencer under the Columns tab you can change the number of divisions that each track will have.
For each step a data-source or shortcut can be assigned to jump to that point in the sequence.
In addition to setting the nominal duration and jumping to particular steps in the sequence, each plugin contains a set of movie-player style transport controls.
These can be used to adjust the playback behavior of the sequencer in a variety of ways.
- Time Slider - Click or use a data-source to jump to any point in the sequence.
- Pause- Stops the playhead for the sequencer from moving on its own.
- Scratch Slider - Click and drag to move the playhead relative to the current position.
- Jump Back / Fwd - Jump back or forward by the amount set by the jump slider.
- Loop Mode - Standard Play Once, Loop, or Reversing Loop options.
- Rate Slider - Speed up, slow down or change the direction of the sequence relative to its nominal duration.
- Reverse Button - Change the playback direction without changing the playback speed.
Each track can publish a value of one of the four value types:
- Index - Each row division represents a specific number value to publish.
- Number - Set column values to any number.
- Boolean - Set on/off state for each column.
- Color - Each row represents a specific color to publish. Click on colors in y-axis to modify.
In addition to the type of data-source published by the track the following settings can be customized:
- Track Name - The name of the track as it appears in the data-source picker and plugin interface.
- Number of Rows - The number of row divisions (not applicable to boolean).
- Interpolation Rate - How far into the step to begin fading to the next column value (not applicable to booleans).
- Publish Normalized Value - Publishes Index and Number data types ranged 0 to 1 instead of a whole number based on the number of rows (on by default).
- Data Receivers for individual columns - For each column set a data-receiver (MIDI, OSC, DMX, or internal data-source) to set the published value.
For color tracks you can also globally set the following options:
- Publish as RGBA- In addition to publishing a color data-source to use with color pickers, the individual RGBA channels are published as numbers ranged 0-1.
- Publish as HSVA- In addition to publishing a color data-source to use with color pickers, the individual HSVA channels are published as numbers ranged 0-1.
In the options section there are also two useful settings for the editor:
- Draw Column Values- Hide or show the number display for index and number types.
- Restrict Clicks to Columns- Change the behavior when clicking and dragging across columns.
The Sticky plugin lets you write notes in your setup- it provides a simple editable text field that you can write in. Formatted text is supported, and images can be embedded inline in the text- the UI is the standard text view for the OS. The plugin can optionally be "locked" by inspecting it, and disabling the "Editable" checkbox in the inspector.
The Syphon Output plugin is how you make video streams in VDMX available to other apps via Syphon. This is a very simple plugin: just create it (you only need one instance of this plugin) and choose the video streams you want to publish. That said, there are a couple things you can do to optimize your setup if your primary use of VDMX is to publish video via Syphon:
- If you want to publish the Canvas/Main Output via Syphon, make sure that "Skip Canvas Rendering" is disabled in the Rendering Preferences.
- If "Display Drives Canvas Rendering" is enabled in VDMX's Rendering Preferences, the rendering speed (framerate) of the canvas/main output is being driven by the refresh rate of the display it appears on. While this looks nice and smooth, it may not be necessary- you may see better overall performance on your machine by disabling this, and manually setting the framerate of the canvas/main output.
The Timecode plugin publishes a data source in VDMX, and is capable of both receiving and sending SMPTE timecode in a variety of formats.
- A single timecode plugin can only receive from one source at a time- it can receive from MTC (MIDI Timecode), LTC (Linear timecode), or from any data source in VDMX (including any MIDI/OSC/DMX data VDMX receives). Timecode plugins can also generate their own timecode locally, using a variety of framerates.
- The values received by a timecode plugin are published in VDMX as a data source as a floating-point number describing the time in seconds. These values can be used to drive cue lists, control movie playback directly, etc.
- A single timecode plugin can have multiple reference times, which are configured in its inspector- the time passed since the last reference time is published as a data source in VDMX, along with the index and name of the reference time.
- A single timecode plugin can publish its value to multiple destinations, in multiple formats. Values can be sent to other devices using MTC, LTC, and OSC.
Two Channel Mixer
A common paradigm for realtime audio/video mixing is the ability to fade between two "channels" (or, in this case, layers). While this is largely built right into VDMX (just grab a layer opacity slider and start having fun), it's convenient for performance reasons to put this control in a dedicated plugin- this is what the Two Channel Mixer plugin is for. Don't be confused: the Two Channel Mixer plugin does NOT do any rendering/mixing/image processing. This plugin just changes the opacity of its target layers!
- The "crossfader" slider fades between the two selected layers.
- The pop-up buttons below the "crossfader" slider select the two layers you want to fade between. Again, this plugin doesn't do any image composition- it just changes the opacity sliders of the layers you select with these pop-up buttons!
- The "Cut" and "Fade" buttons above the crossfade slider let you cut and fade back and forth between the selected layers.
- The "Auto-Fade:" toggle determines whether or not the crossfade slider automatically fades in a layer when you trigger a clip in it.
If you inspect a Two Channel Mixer plugin, its options panel becomse visible and provide you with additional settings:
- The "Fade Duration" slider determines the time (in seconds) it takes the slider to fade from one side to another when you click the "Fade" button or trigger a clip while Auto-fade is enabled.
- The "Layer opacity lookup curves" allow you to set non-linear lookup curves- instead of being limited to a 1:1 relationship between the opacity sliders in the two layers, you can use this to adjust the lookup curves for the layer independently.
Video To DMX
The Video to DMX plugin lets you publish a video source in VDMX as DMX data via Artnet, allowing you to put the video you generate on LED walls and other large-format displays that use DMX as an input source. A single "Video To DMX" plugin can publish a single video stream to a single DMX destination.
- The "Video Source" pop-up button lets you select the video source to publish. Immediately to the right of this is a "BLACK" toggle that blacks out the output if enabled.
- The "Crop Video Source" UI item lets you crop the selected video source- only the cropped area will be published.
- The "Output Dims:" fields allow you to specify the dimensions of the video you'd like to publish- whatever video you cropped will be resized to these dimensions before it is published.
- Video to DMX plugins output a video stream so you can preview the video you're sending to each output device- this is handled automatically, you can just select the video stream in any plugin window.
The inspector for the plugin has more options for determining how the DMX values are to be sent:
- The "First Pixel and Read Direction" pop-up buttons let you select thel ocation of the "first" pixel (Top-left, Top-right, etc), which direction the pixels are to be output in ("Left/Right", "Up/Down"), and how to handle the ends of each line ("Wrap at end"/"Snake at end").
- The "Start DMX Port" lets you select the DMX port you'd like to output on- if this pop-up button is empty, you need to navigate to the "DMX" section of VDMX's preferences and set this up!
- The "Start Channel" text field lets you specify which DMX channel to begin outputting on.
- Next to the "Start Channel" text field is a pop-up button that lets you choose what type of image to output (Grayscale, RGB, HSV, CMYK).
The Wiimote plugin lets you use a wiimote (and a nunchuk plugin if you've got one) with VDMX. Using a wiimote plugin is fairly straightforward: you create the plugin (one per wiimote), click its "DETECT" button, and then connect your wiimote (either by pressing the red button in the battery compartment or by pressing and holding the 1 and 2 buttons simultaneously. Once connected, the data received from the wiimote is published as a series of data sources within VDMX- you can even just use the buttons on your wiimote controllers with hardware learn mode. The Wiimote plugin in VDMX is limited to the basic wiimote, the nunchuk controller, and the "classic" controller- it does *not* support the Wii motion plus add-on, balance board, etc.
If you inspect a wiimote plugin, its options inspector appears and offers you a number of controls for fine-tuning the pitch, yaw, and roll data sources.
Making VDMX Plugins with Quartz Composer
Saving Your Work
At some point, you're going to get things in VDMX arranged the way you like and will want to save that setup so you can use it again. The most common, portable, and generally useful way of saving your VDMX setup is to make a preset- which saves the state of your workspace- and then save a VDMX project file to disk (the project file contains your files and presets).
A project file is the basic document type for VDMX5. A project contains all the information needed to recreate your VDMX workspace:
- All the pages and media files that were in your workspace last time the project was saved, and all the various settings for those files.
- All the presets that were in your workspace (your workspace presets) last time the project was saved, and all the various settings for those presets.
Project files are managed via the "File" menu:
- "New" creates a new project. Any files and pages you loaded are unloaded, all the layers and plugins in the workspace are deleted, and the workspace is generally returned to its default state.
- "Open Project" opens a project file on your computer. Any files and pages that are loaded will be unloaded and replaced with the files from the project- similarly, all the layers and plugins in the workspace are deleted. By default, the first preset in the project file is triggered, but this may be changed in the "Project Files" section of VDMX's preferences.
- "Update Preset and Save Project" is exactly what it sounds like: the currently-selected preset is updated (you'll get the usual warning if no presets are selected, or if the selected preset isn't the last preset triggered) and the project file is then saved to disk. The keyboard shortcut for this is cmd-S because the combination of updating the preset you're working on and then saving it to disk is something you'll probably be doing quite a bit.
- "Save Project (Don't Update Preset)" just saves the project file- no changes are made to any of your presets. If you just wanted to edit some file properties you might want to use this.
- "Save As..." has a similar pair of menu items- one updates the selected preset first, the other doesn't.
- "Revert to Saved" reverts the currently-open project file to its last saved version. This is basically the same thing as just opening the project file again.
The goal of a workspace preset is to allow users to save a "snapshot" of their workspace: by default, a preset created via the Workspace Inspector will save the state of every layer, plugin, and UI item that currently exists so they can be recreated (triggered) later. The "Presets" tab of the Workspace Inspector displays the interface for creating, updating, managing, restoring these top-level presets.
- The dominant UI item in the "Presets" tab is the list of preset. Each preset has a unique name (left column), a thumbnail of your main output taken when the preset was created/updated (middle column), and a Boolean Receiver you can use to trigger the preset from any MIDI/OSC/DMX/data source (right column).
- Click on a preset in the list of presets to inspect it- the Preset Inspector appears in the bottom of the Workspace Inspector window. The preset's receiver- which exists so you can trigger the preset directly from any MIDI/OSC/DMX/data source- also gets inspected, and the corresponding Boolean Receiver Inspector appears in the UI Inspector window.
- Clicking on a preset thumbnail triggers the preset in addition to inspecting it.
- Double-click on a preset to change its name. Click and drag presets to rearrange them. You can create a "hierarchy" of presets (drag one preset onto another, one preset will go inside the other). Nesting presets inside of each other does not affect functionality at all.
- The "Trigger Selected" button triggers the preset selected in the list of presets. If no preset is selected, nothing will happen. The "Prev" button triggers the previous preset, and "Next" triggers the next preset.
- The "New" button creates a new preset- this new preset is basically a snapshot of all the layer and plugins in your workspace (the preset contains all the information VDMX needs to recreate all your layers and plugins).
- The "Update" button updates the currently selected preset so it describes the layers and plugins that are currently in your workspace. The previous contents of the preset are discarded.
- The "Delete" button deletes the currently selected preset.
- The "Copy" and "Paste" buttons copy and paste the selected presets (you can copy and paste presets across project files).
- The slider in the bottom of the Presets section controls the size of the preset thumbnails.
When you select a preset in the Workspace Inspector, that preset gets inspected- and the Preset Inspector will get added to the bottom of the Workspace Inspector window. The preset inspector lets you modify various properties of the preset, some of which alter how that preset is applied to your workspace.
- Most of the space in the Preset Inspector is taken up by the outline view (a list with collapsible items) at its top. This lets you edit how the inspected preset is applied to the workspace.
- "Restore Layers" determines if the layers saved with the preset are restored or not. If it's enabled, the layers will be restored- if it's disabled, then the layer information in your preset will be ignored and the layers in your workspace will be left alone.
- "Restore Plugins" is just like "Restore Layers", but affects whether plugin data is restored or not.
- If you expand either "Restore Layers" or "Restore Plugins", you can further edit details of how each layer component (src, fx, and composition) and plugin in the preset are restored. This is accomplished via a menu for each item:
- "Restore Contents + Window Pos." is the default- both the state of the item and its UI (which window it was in, where the window was) are restored. This is what you want most of the time.
- "Restore Contents" restores the state of the plugin or layer component. If you change the FX component of a layer in a preset to "Restore Contents" then triggering that preset will restore the layer FX chain- but it won't change the window it's currently in. "Restore Contents" will change what your layers and plugins are actually doing- so it will affect the contents of your canvas/main output- but it won't rearrange or move your windows.
- "Restore Window Pos." restores the window-related information about the component you're editing: the size and location of the window/which window it's in, the state of the receiver used to trigger its tab- generally speaking, this affects your UI without affecting the contents of your main output.
- The "Lock Preset" checkbox locks a preset and prevents it from being updated accidentally.
- The "Update Thumbnail" button updates the thumbnail of the selected preset- when you click the button a frame from your canvas/main output is saved with your preset. Please note that "Skip Canvas Render" needs to be disabled for thumbnails to work.
- Presets have a "Description" field you can use to jot down some short notes about your preset.
One of the recurring themes throughout VDMX is the ability to save and recall settings for things at various levels, allowing users to create and access complex interactions and sets of resources. Assets are, as the name implies, another way of storing and saving VDMX-related resources. These assets are global resources- they do not get saved with your project files (they're saved in VDMX's "Application Support" folder), and are available to any project file you open on your machine. Assets are basically the palette of tools available to you, and the asset manager lets you customize and organize those tools. If you've chosen a composition mode, picked out FX in the pop-up button in layer fx chains, or used number fx, you've worked with assets.
There are several different kinds of assets: video FX and chains, composition modes, num fx chains, and text/image generators. The interface for working with the various assets is largely similar:
- Use the pop-up button at the top of the "Assets" section to switch between the different asset types.
- All asset types have two table views with +/-/action toolbars beneath them and a search field.
- The table on the left is a list of high-level categories. You can create your own categories, which is convenient for creating submenus of video fx for a specific purpose, for example. Selecting a category in this table lists all the assets in the category in the table on the right.
- The toolbar beneath the table on the left lets you create and delete categories.
- The table on the right is a list of all the assets in the category which is selected in the table on the left. If you're using the search field, the list of assets in this table is filtered appropriately.
- If an asset's name is red, the file for that asset is missing.
- Un-checking the box next to an asset in the table on the right prevents that asset from appearing wherever assets of that type are listed.
- The toolbar beneath the table on the right lets you perform actions specific to the assets selected in the table above it. This is how you duplicate or delete assets, clean up missing assets, and- in the case of video fx and number fx- create fx chain assets.
- The search field lets you search the available assets by name, description, or both- only the assets in the selected category will be searched.
- Categories that you have created (as opposed to categories which are part of the various FX formats) are customizable- you can drag whatever assets you want into them. Just click on an asset in the table on the right, and drag it into the category in the table on the left.
- Categories that are part of the various FX formats can't be deleted.
Perhaps most importantly, selecting an asset from the list of assets in the right-hand table will inspect it, allowing you to edit the properties of the asset and preview its impact before you add it to your workflow. Many of the inspectors for the specific asset types have identical (or very, very similar) features, too:
- Assets are created automatically for available resources (FX, composition modes, etc) when you launch VDMX- these assets can't be deleted (if you deleted them, you wouldn't be able to access the FX/composition modes/etc- this is a safety measure). Assets that you've duplicated and assets that describe FX chains can be deleted.
- Any changes you make to the asset are kept when you uninspect the asset (or click "Save"). The changes you've made to your assets actually get saved to disk when you save your project file (or when you quit vdmx).
- All of the asset inspectors have a "Description" field. This displays the default description for the inspected asset; if it's a custom asset, the description is editable.
- The "Cancel" button uninspects the selected asset, and any local changes you made to it are discarded.
- The "Revert" button reverts the inspected to its last-saved version.
- The "Duplicate" button makes a copy of the inspected asset with the current settings, and inspects the copy. Any changes to the original asset are *not* applied (they've already been applied to the duplicate).
Assets: Saved Video FX, FX Chains, and Composition Modes
VDMX supports several different FX protocols- CoreImage, Quartz Composer, FreeFrame, and FreeFrame GL. As a result of this, the default VDMX installation on a new mac has immediate access to over a hundred different image filters, and several hundred more are available for download from a wide variety of different sources (to say nothing of your ability to quickly and easily create your own FX and composition modes, particularly with Quartz Composer).
Video FX & Chain Assets are how you organize, retrieve, and save the settings for all of these FX. Every filter/effect VDMX supports has a corresponding asset in VDMX which stores the default settings for the FX- both the properties of the FX-specific UI items as well as the standard wet/dry slider and composition mode. In addition to these default assets, you can create new assets with one or more FX in them, with all the custom settings you'd expect (FX chains).
- The "Use Source" pop-up button contains a list of video sources available to VDMX (this is the same pop-up button found in layer source windows). This lets you choose a video source used to preview the inspected asset- you can see exactly how FX and FX chain assets will look when you apply them to various layers or other video streams.
- The Composition Mode Asset Inspector has two "Use Source" pop-up buttons- one selects a video stream for the top image, the other for the bottom image.
- The "Opacity test slider" in the Composition Mode Asset Inspector (not pictured) lets you preview what the composition mode looks like as it's faded in and out- this is particularly useful for previewing animations or transitions in composition modes created via Quartz Composer.
- If the inspected asset is a video effect or FX chain, the inspector for the actual FX appears immediately below the asset inspector- this is where the UI for the FX is displayed.
- If the inspected asset describes a single effect, the corresponding effect can't be deleted from the asset (nor can the asset be deleted). Use the "Duplicate" button to make a copy- or just make a new chain via the toolbar under the table view in the Workspace Inspector- then customize the new chain as much as you want.
- Below the Vid FX Chain Inspector is a preview of what the inspected asset would look like if images from the chosen source are run through it. Because this is an inspector, it's only running at about 10fps.
Assets: Saved Num FX Chains
Assets: Saved Text and Image Generators
VDMX's preferences are accessed via the "VDMX5" menu. The prefs are split up into several different sections, which are listed in the left side of the window. Select a section to view its settings. Your preferences file is stored in /Users/yourusername/Library/Preferences/com.vidvox.VDMX5.plist.
The appearance of VDMX is governed by hundreds of different colors, fonts, and options- all of which are in the "Colors" section of the preferences.
- When you get a set of colors you like, click the "Save Colors to Prefs" button. This save the current colors to your preferences, where they will be loaded next time you launch VDMX.
- If your colors get reset when you launch VDMX, you didn't save them to the preferences.
- "Revert to last saved prefs" loads any colors that are stored in the prefs. This overwrites any changes you made.
- Sets of colors may be exported so you can use them on other machines or shared with other users. A set of exported colors is called a "Theme". To export the current colors as a theme, enter a name in the supplied field and click the "Export Colors As:" button.
- The "Import Theme:" pop-up button lets you load a set of colors- when you load a theme listed in the pop-up button you'll start using its colors immediately, but the colors don't get saved to your preferences- unless you explicitly save the colors to your prefs, they will be reset when you relaunch VDMX.
- The default location for Themes is the "Themes" folder in your VDMX Resources folder (the default location is /Users/yourusername/Library/Application Support/VDMX/Themes). When you export a theme, this is where it goes- if you get a theme from someone, this is where you need to put it so VDMX can use it.
- Several sections of colors are multiplexed. For example, the set of colors for "Buttons" has a "Background" color. There's a "Background" color for the button's "On" state, another for its "Transition" state, and another for its "Off" state- that's a set of three different colors (you can switch between them with the "On/Transition/Off" radio buttons).
- Some UI items have different sets of colors if they're inspected, if one of their receivers is enabled, or both. To continue the previous example, buttons have three different "background" colors: one for when the button is "On", one for when it's "transition"ing from on to off (the "flash" you see), and one for when it's "Off". Another set of these three colors exists and is used if the button's inspected (the yellow outline can be much more than a yellow outline). A third set of these three colors exists and is used if one of the button's receivers is enabled (this is why some UI items turn green when they have receivers). A fourth set of these three colors exists and is used if the button's inspected and one of its receivers is used. A few other UI items have similar controls.
- The "Files" tab allows for editing the default settings of newly imported files.
- When Lock State is enabled the playback settings for new clips can only be modified using the File Inspector.
- The default Render Size of resolution independent source types, such as CoreImage or Quartz Composer patches, can be set to default to match the size of the canvas, the size of the layer they are playing back on, or to a custom fixed size you can define.
- The Text Style sets the default player for newly created and imported text clips. Choose from any of the styles set up in the Text Assets section of the Workspace Inspector.
- The Image Style sets the default player for newly imported still image files. Choose from any of the image players set up in the Image Assets of the Workspace Inspector or use <Direct Playback> to bypass the QC based players.
- When using the preload option in the media bin, the Max Preloaded Files Per-Page setting in the preferences allows you to set the limit on the number of files that will be preloaded when a page is viewed.
- If you are working with very large image files that can not be handled by your system VDMX will automatically reduce their playback size to match the Max Image Size set in the preferences. If the horizontal or vertical size of an image exceeds the set value the image will be resized on the fly, maintaining the original aspect ratio.
- The "MIDI Sources" tab displays various prefs related to received MIDI data
- The list of MIDI devices is provided to VDMX via OS X's CoreMIDI- you can enable/disable specific MIDI devices via the checkbox in this list. By default, VDMX will automatically enable and receive MIDI data from every MIDI input your system detects.
- The "Default Clock Source" pop-up button lets you choose a default MIDI device on your system to use wherever MIDI clock pickers exist.
- The "Dedicated Controls" tab lets you assign specific MIDI input sources as data sources while simultaneously removing their ability to trigger "Detects". This option was added for situations where you're sending control data between machines, but you don't want this control data to accidentally trigger any MIDI "Detects" you do (passing accelerometer or audio analysis data, for example). Simply click the "Detect New" button to start an auto-detect for the MIDI source you want to turn into a dedicated data source.
- The "Display Options" tab lets you choose whether you want to use natural names for MIDI notes or not.
- The "Regex-based wildcard address space" checkbox enables or disables regex-based pattern matching for OSC messages VDMX receives. In other words, if the address of a received OSC message contains a regex string, the message will be dispatched to every OSC address in VDMX that satisfies the regex query. The vast, overwhelming majority of users have no use for this and it is disabled by default.
- The "Input Ports" tab lets you create and manage OSC input ports which VDMX receives OSC data from. By default, VDMX creates a single OSC input that uses port '1234'. The presence of this OSC input is announced via bonjour/zero-configuration networking (other apps that support this will automatically "see" VDMX's input port as a destination). You can change the port by double-clicking on it, and create or delete ports by using the relevant buttons.
- The "Dedicated Controls" tab works identically to MIDI's "Dedicated Controls" tab.
- The "Output Ports" tab lets you configure outputs which VDMX uses to send OSC data to other machines. VDMX supports bonjour/zero-configuration networking, and will automatically create OSC outputs for any software or hardware on your network that uses bonjour.
- The "ArtNet Network" pop-up menu sets which network device (AirPort, Ethernet, etc.) to send and receive DMX data over.
- The "Dedicated Input Ports" number field sets the number of input universes to receive over ArtNet. These ports will be visible to other ArtNet controllers on the same network. Using the table you can specify the SubNet and Universe for each input port.
- The "Dedicated Out Ports" number field sets the number of output universes to send over ArtNet. These ports will be visible to other ArtNet controllers on the same network. Using the table you can specify the SubNet and Universe for each ouput port.
- The "Network Browser" displays other devices broadcasting on the ArtNet network. The Auto Setup Inputs and Outputs buttons will configure VDMX based on the detected devices.
The "Project Files" preferences let you decide whether or not the first preset in a project gets triggered when you open it.
The "Recording" section of the preferences lets you set some default recording properties for video inputs. Please note that these settings only apply to video recorded directly from a digitizer or capture hardware.
The rendering preferences are substantial- please keep in mind that each of these preferences operates completely independently of any of the others- there are literally hundreds of possible combinations for the rendering prefs, each with a different effect on your system, so it helps to know what each one does "behind the scenes".
- The "Restore default prefs!" button restores the default rendering preferences for your machine. Experiment without fear! If you get lost, just click this button and all will be restored.
- "QC antialiasing" lets you set the level of antialiasing applied to QC compositions. This affects all QC composition (whether they're loaded in VDMX as sources, FX, plugins, or whatever else). The default is 0 (no antialiasing); if you're going to set this to a non-0 number, you should really restart VDMX. If you don't restart VDMX, you won't be able to tell the difference between 1 and 8.
- "Flash Quality" lets you set the quality at which flash files render in VDMX. This is a flash-specific option (available in other apps typically by right-clicking on the composition and setting the quality). "High" quality is the default- it looks the nicest, but definitely runs a lot slower than "Low".
- "Enable Multi-Threaded Rendering" is disabled by default on most machines. If this is enabled, each layer will render on its own thread and has its own framerate. While this has advantages- particularly on multi-core machines- when it comes to parallelizing processing, the reality of the situation is that many of the FX formats VDMX uses aren't threadsafe: they may hang, crash, or simply run poorly if multi-threaded rendering is enabled. If this happens, VDMX will also hang, crash, or run slowly- so this is disabled by default most of the time.
- "Display Drives Canvas Render" should be enabled by default. If this is disabled, the "Canvas" will render on its own thread- while this approach lets you set an explicit framerate (which might be nice if you're working with Syphon), any sync issues between the refresh rate of your monitor and this rendering thread will result in what appears to be dropped frames. Letting the display drive canvas rendering typically results in smoother output- which means a higher framerate, and usually a higher impact on your system.
- "VBL Sync?" should be enabled by default. This option enables or disables vertical blank synchronization- the ability to flush drawing in time with the screen. If you disable this, frames might appear to draw faster- but you might also see "tearing" (the image displayed onscreen consists of half of one frame and half of another- you can see where the computer was writing to the buffer). If you enable this, you won't see tearing- but if you're pushing your GPU hard you may start to see some dropped frames. Generally speaking, dropped frames appearing slightly earlier isn't enough of a problem to justify the distraction of tearing (unless you're going for that sort of aesthetic).
- "Skip Canvas Render?" is probably enabled by default on your machine. The Canvas is the composited result of all your top-level layers, and in order to display it onscreen VDMX has to composite all your layers, rendering them to an image (the "Canvas" image) which then gets drawn onscreen. This process adds an extra rendering pass- if you skip compositing the top-level layers (which has to occur at the canvas resolution- and that can be potentially massive) beforehand we can potentially save a lot of work for the computer by just compositing them once in the output. This approach has some drawbacks, though: since the "Canvas" image isn't being composited and then displayed, you can't preview the "Canvas/Main Output", apply FX to the Canvas, or use QC-based composition modes for any of the top-level layers (they'll default to their last-used or default CoreImage composition modes). This is an option we expect a lot of people to disable- it's a great speed-boost if you need it, but if you have the horsepower it's nice to have a preview and FX on the output.
- "Double-buffer output window?" is exactly what it sounds like. under some circumstances, on some machines, double-buffering the output window yields a slight performance benefit. most of the time, it doesn't.
- "Output throttling mode" These options let you determine how much (if any) throttling VDMX does on its drawing. The general idea behind these is that if you overload your GPU then performance starts to degrade sharply- so some people like to throttle their output to achieve a more consistent performance profile (at the expense of fast framerates).
- "Every refresh" This is the default on most (if not all) machines. Every time your display refreshes, VDMX will ask your GPU to display a frame of output. This results in the smoothest output (at the refresh rate of your display if the "Display drives canvas renering" is enabled), but the highest GPU/CPU usage and interaction.
- "DB, skip if busy" Double-buffered output, but redraws are skipped if the GPU is busy. Frame A is drawn, frame B is drawn, the next frame isn't submitted until the drawing commands for frame A have finished executing, etc.
- "SB, skip if busy" Single-buffered output, but redraws are skipped if the GPU is busy. Frame A is drawn, and drawing commands for frame B won't be submitted to your GPU until the drawing commands from frame A have finished executing. This typically results in the most consistent output, but usually means your framerate is half the refresh rate of your monitor. If you're going to experiment with something, this is probably what you want to experiment with. This is also the default on machines with slow GPUs or drivers that seem to have problems under some circumstances.
- "Default Canvas Resolution & FPS:" sets the resolution/framerate (if applicable) of the Canvas when you make a new project or first launch VDMX. It does *not* change the resolution of the Canvas in your workspace!
- "Default Layer FPS:" sets the default framerate for newly-created layers. This only applies if multi-threaded rendering is disabled, and the default layer framerate may be overridden (if you trigger a file with an explicit framerate, for example).
The "Slider" preferences contains the soft takeover settings for sliders described here.
The "Button" preferences contains the soft takeover settings for buttons described here.
- The "VDMX Resources" path determines where VDMX stores its plugins, qc composition modes, qcFX, qc image and text sources, templates, themes, etc.
- The "Flash Plugin" path lets you determine which flash plugin you want to use. By default this points to the standard location on your system for the flash plugin- if flash isn't working for you, please make sure the flash plugin is installed on your machine!
- "Complete Hide Dock?" lets you completely disable the dock while VDMX is the foremost application.
- The "Add/Replace" radio buttons let you set the default mode in layer FX windows (new FX will either be added to the end of the existing chain or will replace the existing chain entirely).
- The function of the "Show Starting Point window on launch?" toggle should be self-evident.
Quartz Composer is a groundbreaking node-based graphics development environment that allows you to explore the incredible power of the graphics stack of Mac OS X Tiger. With Quartz Composer, you can easily combine the capabilities of Cocoa, Quartz 2D, Core Image, OpenGL, and QuickTime, all using an approachable visual programming paradigm. Quartz Composer can be used to prototype Core Image filters, make data-driven visual effects, and create live performance animations.
Quartz Composer is free, easy to pick up, and offers people with absolutely no programming experience a comfortable way to create stunning interactive pieces. As such, we do our best to support the aspects of it that we think are most advantageous- its ease of use and interactivity. There are several different ways to use Quartz Composer with VDMX:
Trigger QC compositions in VDMX
The quickest way to get your Quartz Composer patches doing something in VDMX is to simply drag them into a media bin, (or choose "Import Media" from the file menu) and trigger them in a layer. Your QC patch may then be triggered and played on a layer just like any other media file. If your QC patch has any published inputs, VDMX will automatically create UI items of the appropriate type (slider, button, color picker, text field, video source picker, etc) for them.
Passing control data and images from VDMX into patches using Published Inputs
Quartz Composer consists of objects which are connected together with patch cords. The "Input Splitter" object lets you make inputs in patches; data may be passed to objects through these inputs. If you make an input splitter in the top level of your patch and publish it, VDMX will attempt to make a UI item for your input; different types of inputs (numbers, toggles, colors, etc.) get different types of interface items.
- Boolean-type inputs will be represented in VDMX as a toggle button (on/off)
- Index-type inputs will be represented in VDMX as a pop-up button. The number of items in the menu is determined by the maximum value set in the node inspector, such that the items in the menu range from 0 to the maximum value minus one. If the input is specified as having labeled indices, the menu items in the menu will correspond to the provided labels.
- Number-type inputs will be represented in VDMX as a standard slider, with a range determined by the minimum and maximum values set in the inspector. If no min/max values are specified, the slider will be ranged 0.0-1.0.
- Color-type inputs will be represented in VDMX as a standard RGBA/HSVA color picker.
- String-type inputs will be represented in VDMX as a text field.
- Image-type inputs will be represented in VDMX as a pop-up button with a list of all available video sources (other layers, video inputs, syphon sources, etc)
- Structure-type inputs are used to represent input types that are not of the aforementioned types, and can be represented in VDMX as several different UI items, depending on the name of the of the published input.
- If the published name of the structure-type input includes the letters "XY", VDMX will create a 2d point-type UI item
- If the published name of the structure-type input includes the letters "MultiButton", followed by two dimensions, VDMX will create a multi-button UI item, with the passed dimensions. For example, a structure-type input splitter published as "ButtonField_MultiButton_2x2" will create a 2x2 multi-button UI item labeled as "ButtonField" in VDMX. The same exact UI item would be created if the name was "ButtonField MultiButton 2x2", "ButtonField-MultiButton-2x2", or "ButtonField-MultiButton-2-2". The values of the buttons will be passed to the composition as an array.
- If the published name of the structure-type input includes the letters "MultiSlider", followed by two dimensions, VDMX will create a multi-slider UI item, with the passed dimensions. The naming pattern for this UI item matches that of multi-button inputs.
- If you have a string-type input published with "FontMenu" anywhere in its name, VDMX will create a pop-up button with a list of all the system fonts (the name of the font will be passed to QC when you select it).
- If you have a number-type input published with "VDMXBPM" anywhere in its name, VDMX will automatically pass the BPM of your clock to your composition. No UI item is created, this is handled entirely behind the scenes.
- If you have a number-type input published with "MeasurePosition" anywhere in its name, VDMX will automatically pass the measure position to this input as a value ranged 0.0-1.0.
Built-in QC sources
VDMX offers a number of built-in media files and video sources that are quickly accessible in the "Use Source:" pop-up button in the layer source UI. If you want your QC composition to be listed here, place it in the "qcSources" folder in your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). It will immediately be listed as an available effect in VDMX, and can be previewed in the Workspace Inspector's "Assets" tab or added to layers.
Making Video FX with QC
If you add an image-type input splitter to your patch and publish it as "inputImage", the composition can be used as an image filter in VDMX- just place it in the "qcFX" folder in your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). It will immediately be listed as an available effect in VDMX, and can be previewed in the Workspace Inspector's "Assets" tab or added to layers.
QC-based Composition Modes
QC compositions can be used as composition modes in VDMX (they can be used to composite layers together) if they meet the following requirements:
- It must have an image-type input splitter published as "background". video from the "background" layer will be sent to this input.
- It must have an image-type input splitter published as "foreground". video from the "foreground" layer will be sent to this input.
- It must have a number-type input splitter (ranged 0.0-1.0) published as "opacity"- the opacity of the "foreground" layer will be passed to this input.
- The composition must be placed in the "qcCompModes" folder of your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu).
QC-based VDMX Plugins
QC compositions can be used as plugins in VDMX- when loaded as a plugin, VDMX will not only create UI items for any published inputs in your patch, but any outputs you publish will be made available in VDMX as either a video source (if the published output is an image-type splitter) or a data source (if it's a bool/number/color/string/etc). This allows you to use QC to program complicated mathematical or logical behaviors that both receive data from and send data back to VDMX.
QC Text Sources- Using QC to Render Text
Text files in VDMX can be triggered and played back on layers- you can customize how your text files are rendered by creating Quartz Composer patches that will be used to render text. To be used as a text source, your QC composition must have a string-type input published as "FileInput", and it must be placed in the "qcTextSources" folder of your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). Once you trigger a text file, you can choose which QC compositions is used to render its contents using the appropriate pop-up button in the layer source controls- VDMX will automatically display a browser for your text file that allows you to trigger individual words/lines/etc (these words/lines/etc will be passed to your patch via the "FileInput").
Vuo is a node-based development environment, similar in many ways to Quartz Composer while at the same time having a lot of fundamental differences that make it a substantially unique environment with a vibrant user community that often overlaps with Quartz Composer. You can find more information here: vuo.org
Vuo shares many of the same benefits as Quartz Composer, and accordingly we have made it an integral part of VDMX, which has many different ways to work with Vuo.
A word on Protocols
Protocols define required behavior for a protocol- Vuo explicitly defines two protocols: the "Image Generator" protocol, and the "Image Filter" protocol. Patches that conform to the "Image Generator" protocol must have inputs for "width", "height", and "time" values and an image-type output published as "outputImage". "Image Filters" must have an image-type input published as "image", a real-type input published as "time", and an image-type output published as "outputImage". If your Vuo composition doesn't adhere to these protocols, VDMX won't be able to exchange data with it, and it won't work. You can examine and modify the protocols your composition conforms to via the "Protocols" sub-menu in the Vuo Editor's "Edit" menu.
Separate Process or Same Process?
Vuo compositions can be run in the same process as VDMX, or they can be run in another process (as another application that passes data back and forth with VDMX). Running Vuo compositions in a separate process is safer- if Vuo crashes for any reason, VDMX will be unaffected- but file triggering will be slightly slower (if you need super-fast triggering you may want to disable this), and there may be more overhead when passing image data back and forth on some hardware as a result of performance differences in OS X's drivers. The default behavior is to run Vuo comps in another process, but you can change this behavior in the "Vuo" section of VDMX's preferences.
Trigger Vuo compositions in VDMX
The quickest way to get your Vuo compositions doing something in VDMX is simply to drag them into a media bin (or choose "Import Media" from the file menu) and trigger them on a layer. If the Vuo composition conforms to Vuo's "Image Generator" protocol, there will be a delay of a few seconds the first time you trigger it while Vuo compiles your patch (all subsequent triggers- even after relaunching VDMX- will be immediate), after which it will be played on your layer just like any other media file. If your Vuo composition has any published inputs, VDMX will automatically create UI items of the appropriate type (slider, button, color picker, text field, video source picker, etc) for them.
Passing control data and images from VDMX into patches using Published Inputs
Vuo consists of objects which are connected together with patch cords. A complete description of how to use and work with Vuo is beyond the scope of this wiki (Vuo's documentation is excellent), but generally speaking you publish an input in your patch by dragging from the desired input to the "Inputs" sidebar on the left-hand side of the editor window. VDMX will automatically attempt to make a UI item for your published inputs; different types of inputs get different types of interface items.
- Image-type inputs will be represented in VDMX as a pop-up button with a list of all available video sources (other layers, video inputs, syphon sources, etc).
- Real- and Integer-type inputs will be represented in VDMX as sliders. Vuo lets you set a default min and max value (right-click on the published input and choose "Edit Details" to set this)- the slider in VDMX will have its range set by these values.
- Color-type inputs will be represented in VDMX as a standard RGBA/HSVA color picker.
- Boolean-type inputs will be represented in VDMX as toggle buttons (on/off).
- Point-type inputs will be represented in VDMX as a 2d point picker. The range of the values VDMX passes to Vuo will be based on the dimensions at which the Vuo composition is being rendered (VDMX passes pixel-scale coords to Vuo, which at this time does not offer a way to specify the min/max values of its point-type inputs).
- Text-type inputs will be represented in VDMX as a text field.
- If you have a string-type input published with "FontMenu" anywhere in its name, VDMX will create a pop-up button with a list of all the system fonts (the name of the font will be passed to Vuo when you select it).
- If you have a number-type input published with "VDMXBPM" anywhere in its name, VDMX will automatically pass the BPM of your clock to your composition. No UI item is created, this is handled entirely behind the scenes.
- If you have a number-type input published with "MeasurePosition" anywhere in its name, VDMX will automatically pass the measure position to this input as a value ranged 0.0-1.0.
Built-in Vuo sources
VDMX offers a number of built-in media files and video sources that are quickly accessible in the "Use Source:" pop-up button in the layer source UI. If you want your Vuo composition to be listed here, place it in the "vuoSources" folder in your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). It will immediately be listed as an available effect in VDMX, and can be previewed in the Workspace Inspector's "Assets" tab or added to layers.
Making Video FX with Vuo
If your Vuo composition conforms to the "Image Filter" protocol, it can be used as an image filter in VDMX- just place it in the "vuoFX" folder in your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). It will immediately be added as an available effect in VDMX, and can be previewed in the Workspace Inspector's "Assets" tab or added to layers.
Vuo-based VDMX Plugins
Vuo compositions can be used as plugins in VDMX- when loaded as a plugin, VDMX will not only create UI items for any published inputs in your patch, but any outputs you publish will be made available in VDMX as either a video source (if the published output is an image-type splitter) or a data source (if it's a bool/number/color/string/etc). This allows you to use Vuo to program complicated mathematical or logical behaviors that both receive data from and send data back to VDMX.
Vuo Text Sources- Using Vuo to Render Text
Text files in VDMX can be triggered and played back on layers- you can customize how your text files are rendered by creating Vuo patches that will be used to render text. To be used as a text source, your Vuo composition must have a string-type input published as "FileInput", and it must be placed in the "vuoTextSources" folder of your VDMX Assets folder (choose "Open Assets Folder in Finder" from VDMX's "Help" menu). Once you trigger a text file, you can choose which Vuo compositions is used to render its contents using the appropriate pop-up button in the layer source controls- VDMX will automatically display a browser for your text file that allows you to trigger individual words/lines/etc (these words/lines/etc will be passed to your patch via the "FileInput").
ISF stands for "Interactive Shader Format", and is a file format that describes a GLSL fragment shader, as well as how to execute and interact with it. The goal of this file format is to provide a simple and minimal interface for image filters and generative video sources that allows them to be interacted with and reused in a generic and modular fashion. ISF is nothing more than a [slightly modified] GLSL fragment shader with a JSON blob at the beginning that describes how to interact with the shader (how many inputs/uniform variables it has, what their names are, what kind of inputs/variables they are, that sort of thing). ISF isn't some crazy new groundbreaking technology- it's just a simple and useful combination of two things that have been around for a while to make a minimal- but highly effective- filter format.
ISF is a very simple file format, and has more inherent limitations than QC/CI/Vuo/FreeFrame. That being said, a tremendous amount is still possible with a multi-pass fragment shader- and the format's simplicity means that ISF media generally runs faster and has fewer bugs and problems than other formats, while also being faster and easier to put together.
The open-source ISF Editor is distributed with VDMX in the "Extras" folder on the dmg, and VDMX also installs nearly 200 ISF files- both generators and filters- on your system (in /Library/Graphics/ISF) where VDMX and any other software that supports ISF can use them. The ISF Editor also has a built-in installer for a QuickLook plugin that renders thumbnails for ISF files in the Finder. More information about ISF- including our open-source implementation- can be found here: http://www.vidvox.net/rays_oddsnends/ISF.html
Making Video FX and Built-In Image Sources with ISF
The ISF Editor can be used to create new ISF files- as long as there is an "image"-type input named "inputImage", the ISF file can be used as an image filter. The ISF file can be placed in the "ISF" folder in your VDMX Assets folder, but it's often more convenient to install them in a more general location where they can be used by other software- /Library/Graphics/ISF and ~/Library/Graphics/ISF are the default locations. Any ISF files in any of these folders will be made available in VDMX (you don't have to put FX in one folder and sources in another).