DMXIS macros are written in Python language. To be specific, DMXIS runs Python version 2.6. All the usual Python system libraries, functions and programming constructs are available within a Python macro. The user can apply macros from the Macros button on the main DMXIS screen.
A macro can modify any on-screen DMXIS attribute, for example fader levels and oscillator settings. Some higher level functions (e.g. iterating though & saving banks & presets) is also available. However, It is important to realise that macros do not run in realtime, and can not directly manipulate the DMX data being generated. Think instead of macros as programming shortcuts that let the user quickly set up a number of DMX channel settings, or perform some high level maintenance task (like copying a setting between different presets).
DMXIS macros are stored in the "Macros" folder of the DMXIS installation folder - click here for more details of the exact locations.
Structure of a macro
A DMXIS macro is typically a simple block of Python code with no user interaction. Macros cannot query the user for custom information. A macro can only query the DMXIS engine for basic information (typically the currently selected channels) and display a single information dialog once the macro code has completed execution (or if the macro fails for some reason).
Code: Select all
# Get the user selected channels
ns = GetNumSelCh
if ns==0:
Message("Select some channels first!")
# Set all selected channel faders to halfway point
for i in range(ns):
SetChVal(GetSelCh(i), 128)
- DMXIS scans the Macros folder every time the user clicks on the "Macros" button. So, there is no need to restart DMXIS every time you modify a macro or create a new one. Simply save your macro file within your editor, then select it in the DMXIS GUI.
- Each macro lives in a single .py file - simply use your favourite text editor to edit the macro files.
- You can create any folder structure you like within the main 'Macros' folder, and they will appear as submenus in the DMXIS interface.
- Do not modify the 'Macros/System' or 'Macros/Python' folders.
In DMXIS, select the "Advanced > Macro output console" menu option to see the standard Python output terminal. In here, you will see any Python interpreter errors, to assist you in debugging your scripts.
You can also generate your own debug output by using the standard Python 'print' keyword in your macros. For example, this simple macro will display the current value of every selected fader in the macro output console window:
Code: Select all
n = GetNumSelCh()
for i in range(n):
chNum = GetSelCh(i)
print 'Channel %d value = %d' % (chNum, GetChVal(chNum))
A full reference list for the various DMXIS specific functions available within a macro now follows. Most functions are grouped as get/set pairs, to query or modify a particular attribute. As with all programming languages, the best way to learn is by example. So in addition to this guide, take a look through the standard factory macros to see what is possible.
Channel selection
integer GetNumSelCh
- Returns the number of currently selected channel faders.
- Returns the DMX channel offset of a selected channel.
- idx = 0 to GetNumSelCh return value minus 1
- Selects or deselects the fader for the given DMX channel.
- ch = 0 to 511
- sel = 0 (deselect the fader) or 1 (select the fader).
string GetChName(integer ch)
- Returns the name of the given DMX channel. Useful for macros that only work on specific channel types (e.g. "Pan" or "Tilt" channels)
- ch = 0 to 511
integer GetChVal(integer ch)
SetChVal(integer ch, integer val)
- Sets or gets the fader level for the given DMX channel.
- ch = 0 to 511
- val = 0 to 255
integer GetChInvert(integer ch)
- Modifies or retrieves the 'Invert' knob value level for a given DMX channel.
- ch = 0 to 511
- val = 0 (invert off) or 1 (invert on)
SetChEnabled(integer ch, integer val)
integer GetChEnabled(integer ch)
- Enables or disables a given DMX channel. This is used to implement the critical "channel masking" feature of DMXIS.
- ch = 0 to 511
- val = 0 (channel disabled) or 1 (channel enabled)
SetOscAmount(integer ch, float val)
float GetOscAmount(integer ch)
- Sets or gets the amount of oscillation for the given DMX channel.
- ch = 0 to 511
- val = 0.0 (no oscillation) to 1.0 (full oscillation). Higher values will "overdrive" the oscillator, making the fader "clip" at 0 and 255. This can be a useful effect.
float GetOscChase(integer ch)
- Sets or gets the oscillator phase for the given channel. By setting a range of channels to a different phase value, you can create complex chases.
- ch = 0 to 511
- val = 0.0 to 1.0. A value of 0.5 makes the oscillator run precisely 180 degrees out of phase.
integer GetOscSpeed(integer ch)
- Sets or gets the oscillator speed for the given channel. This is one of a set of fixed tempo-based values.
- ch = 0 to 511
- val 0 = 1/16 bar, 1 = 1/8 bar, 2 = 3/16 bar, 3 = 1/4 bar, 4 = 3/8 bar, 5 = 1/2 bar, 6 = 3/4 bar, 7 = 1 bar, 8 = 2 bars, 9 = 3 bars, 10 = 4 bars, 11 = 6 bars, 12 = 8 bars, 13 = 12 bars, 14 = 16 bars, 15 = 24 bars, 16 = 32 bars, 17 = 48 bars, 18 = 64 bars, 19 = 96 bars, 20 = 128 bars
float GetOscShape(integer ch)
- Sets or gets the oscillator shape for the given channel. The effect this has on the waveform depends on the oscillator type selected (see the DMXIS manual for more information)
- ch = 0 to 511
- val = 0.0 to 1.0
integer GetOscType(integer ch)
- Sets or gets the oscillator waveform for the given channel.
- ch = 0 to 511
- val 0 = disable oscillator, 1 = sine, 2 = square, 3 = triangle, 4 = saw up, 5 = saw down
SetStLevel(integer ch, float val)
float GetStLevel(integer ch)
- Sets or gets the sound tracker level.
- ch = 0 to 511
- val = 0.0 to 5.0
integer GetStBand(integer ch)
- Sets or gets the sound tracker EQ band for the given channel.
- ch = 0 to 511
- val 0 = sub, 1 = low, 2 = mid, 3 = high
float GetStAttack(integer ch)
- Sets or gets the sound tracker attack time (in ms).
- ch = 0 to 511
- timeMs = 0.0 to 10.0
float GetStRelease(integer ch)
- Sets or gets the sound tracker release time (in ms).
- ch = 0 to 511
- timeMs = 0.0 to 250.0
integer GetStDir(integer ch)
- Sets or gets the sound tracker direction for the given channel.
- ch = 0 to 511
- val 0 = up, 1 = down
The following functions are useful for macros which perform global edits (e.g. making a modification across all presets in a bank, or every preset in a show). See the "Global Edits" factory macros for example usage.
integer GetNumBanks
- Returns the number of banks in the currently loaded show.
- Returns the name of the given bank
- idx = 0 to number of banks in show - 1
- Loads the given bank (by index number)
- idx = 0 to number of banks in show - 1
- Loads the given bank (by bank name)
- s = bank name
- Returns the number of banks in the currently loaded bank.
- Returns the name of the given preset
- idx = 0 to number of presets in the current bank - 1
- Loads the given preset (by index number)
- idx = 0 to number of presets in bank - 1
- Loads the given preset (by preset name)
- s = preset name
- Overwrites the currently loaded preset with the current settings
A couple of functions for basic fixture profile handling. See the "Fixture Setup" category of factory macros for example usage.
RepeatLastFixture
- Takes the most recently loaded fixture profile, and loads another one at the next available free channel
- Unloads any current fixture profile from the specified channel.
- ch = 0 to 511
- Displays the given message in the DMXIS GUI. Use this to optionally tell the user of a problem (e.g. "select an RGB channel first").