Posted on

Programming Show Buddy Active macros

Programming Show Buddy Active macros

Show Buddy Active macros are written in Python language. To be specific, Show Buddy Active runs Python version 3.10.

All the usual Python system libraries, functions and programming constructs are available within a Python macro. You can execute macros from the Macros button on the Show Buddy Active screen.

A macro can modify any on-screen Show Buddy Active attribute, for example fader levels and oscillator settings. Some higher level functions (e.g. iterating though and 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 you quickly set up a number of DMX channel settings, or perform some high level maintenance task (like copying a setting between different presets).

Macros are stored in the “Macros” folder of the Show Buddy Active installation folder.

Structure of a macro

A macro is typically a simple block of Python code with no user interaction. Macros cannot prompt for custom information. A macro can only query the Show Buddy Active 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).

Get the 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)

Writing macros

Show Buddy Active scans the macros folder every time you click on the “Macros” button. So, there is no need to restart the software every time you modify a macro or create a new one. Simply save your macro file within your editor, then select it from the “Macros” button.

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 Show Buddy Active interface.

Do not modify the ‘Macros/System’ or ‘Macros/Python’ folders

Debugging macros

In Show Buddy Active, 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:

n = GetNumSelCh()
for i in range(n):
   chNum = GetSelCh(i)
   print 'Channel %d value = %d' % (chNum, GetChVal(chNum))

Function reference

A full reference list for the various 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.

A note on channel numbers

Many of the following functions require a channel in the range 0-1023 (for 2 universe licenses) or 0-8191 (for 16 unlverse licenses).

The channel is (universe – 1) * 512 + fader – 1.
For example, fader 107 in universe 2 = channel 618

        General functions

        Message(string msg)
        Displays the given message as a dialog window in the Show Buddy Active GUI. Use this to optionally report a problem (e.g. “select an RGB channel first”).

        Effects control

        EnableEffects
        DisableEffects
        Switches the “Effects” tab on or off.

        Channel selection

        integer GetNumSelCh
        Returns the number of currently selected channel faders.

        integer GetSelCh(integer idx)
        Returns the DMX channel offset of a selected channel.

        • idx = 0 to GetNumSelCh return value minus 1

        array GetAllSelCh(False)
        Convenience function to get all selected channels. Example use:

        # Set all selected channels to 150
for ch in GetAllSelCh(False):
   SetChVal(ch, 150)

        SelectCh(integer ch, integer sel)
        Selects or deselects the fader for the given DMX channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • sel = 0 (deselect the fader) or 1 (select the fader).

        Channel names

        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 1023 (or 8191 for Show Buddy Active Max)

        General channel settings

        integer GetChVal(integer ch)
        SetChVal(integer ch, integer val)
        Sets or gets the fader level for the given DMX channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val = 0 to 255

        SetChInvert(integer ch, integer val)
        integer GetChInvert(integer ch)
        Modifies or retrieves the ‘Invert’ knob value level for a given DMX channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val = 0 (invert off) or 1 (invert on)

        Channel masking

        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 Show Buddy Active.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val = 0 (channel disabled) or 1 (channel enabled)

        Oscillator settings

        SetOscAmount(integer ch, float val)
        float GetOscAmount(integer ch)
        Sets or gets the amount of oscillation for the given DMX channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • 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.

        SetOscChase(integer ch, float val)
        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 1023 (or 8191 for Show Buddy Active Max)
        • val = 0.0 to 1.0. A value of 0.5 makes the oscillator run precisely 180 degrees out of phase.

        SetOscSpeed(integer ch, integer val)
        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 1023 (or 8191 for Show Buddy Active Max)
        • 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

        SetOscShape(integer ch, float val)
        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 user manual for more information)

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val = 0.0 to 1.0

        SetOscType(integer ch, integer val)
        integer GetOscType(integer ch)
        Sets or gets the oscillator waveform for the given channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val 0 = disable oscillator, 1 = sine, 2 = square, 3 = triangle, 4 = saw up, 5 = saw down

        Sound Tracker settings

        SetStLevel(integer ch, float val)
        float GetStLevel(integer ch)
        Sets or gets the sound tracker level.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val = 0.0 to 5.0

        SetStBand(integer ch, integer val)
        integer GetStBand(integer ch)
        Sets or gets the sound tracker EQ band for the given channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val 0 = sub, 1 = low, 2 = mid, 3 = high

        SetStAttack(integer ch, float timeMs)
        float GetStAttack(integer ch)
        Sets or gets the sound tracker attack time (in ms).

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • timeMs = 0.0 to 10.0

        SetStRelease(integer ch, float val)
        float GetStRelease(integer ch)
        Sets or gets the sound tracker release time (in ms).

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • timeMs = 0.0 to 250.0

        SetStDir(integer ch, integer val)
        integer GetStDir(integer ch)
        Sets or gets the sound tracker direction for the given channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)
        • val 0 = up, 1 = down

        Bank & preset functions

        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.

        string GetBankName(integer idx)
        Returns the name of the given bank

        • idx = 0 to number of banks in show – 1

        LoadBank(integer idx)
        Loads the given bank (by index number)

        • idx = 0 to number of banks in show – 1

        LoadBank(string s)
        Loads the given bank (by bank name)

        • s = bank name

        integer GetNumPresets
        Returns the number of banks in the currently loaded bank.

        string GetPresetName(integer idx)
        Returns the name of the given preset

        • idx = 0 to number of presets in the current bank – 1

        LoadPreset(integer idx)
        Loads the given preset (by index number)

        • idx = 0 to number of presets in bank – 1

        LoadPreset(string s)
        Loads the given preset (by preset name)

        • s = preset name

        SaveCurrentPreset
        Overwrites the currently loaded preset with the current settings

        Fixture profile functions

        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

        RemoveFixture(integer ch)
        Unloads any current fixture profile from the specified channel.

        • ch = 0 to 1023 (or 8191 for Show Buddy Active Max)