Scripting

This section will describe how to use the scripting API to add custom macro conditions and actions.
The API is not limited to Python, but the examples showcased here will only be using Python.

Examples

Custom macro condition

This examples shows how to register a new condition type which will randomly evaluate to true based on provided user input percentage in the range from 0 to 100:

import obspython as obs
import threading  # Required by advss helpers
import random

CONDITION_NAME = "Random condition"


###############################################################################
# This function will define the UI for the custom condition type based on a obs_properties object.
# In this case only a single float selection field for specifying the probability of returning true.
# This isn't mandatory.
# You can also have a condition without any additional UI elements.
###############################################################################
def get_condition_properties():
    props = obs.obs_properties_create()
    obs.obs_properties_add_float(
        props, "probability", "Probability of returning true", 0, 100, 0.1
    )
    return props


###############################################################################
# You can provide default values for each of the settings you have defined earlier.
# This isn't mandatory.
# You can also have a condition without any settings to be modified.
###############################################################################
def get_condition_defaults():
    default_settings = obs.obs_data_create()
    obs.obs_data_set_default_double(default_settings, "probability", 33.3)
    return default_settings


###############################################################################
# This function will be used by the advanced scene switcher to determine if a condition evaluates to true or false.
# The settings for each instance of this condition type will be passed via the data parameter.
###############################################################################
def my_python_condition(data):
    target = obs.obs_data_get_double(data, "probability")
    value = random.uniform(0, 100)
    return value <= target


###############################################################################
# Let's register the new condition type
###############################################################################
def script_load(settings):
    advss_register_condition(
        CONDITION_NAME,
        my_python_condition,
        get_condition_properties,
        get_condition_defaults(),
    )


###############################################################################
# Deregistering is useful if you plan on reloading the script files
###############################################################################
def script_unload():
    advss_deregister_condition(CONDITION_NAME)


###############################################################################
########################### boilerplate code below ############################
###############################################################################

This is the custom condition type we defined with this script in action:

As you can see the frequency at which this condition returns true depends on the provided input value, just as we expect it to.

Registering an action would be identical to the example above, but instead of passing a function which returns a boolean value to advss_register_condition, you would pass a function performing your desired actions to advss_register_action.

The boilerplate code mentioned above can be found here. (TODO) Usually you can just copy it directly into your script without any modifications.

Detailed API description

The advanced scene switcher offers the following procedure handlers:

• bool advss_register_script_action(in string name, in ptr default_settings, out string properties_signal_name, out string trigger_signal_name)
• bool advss_register_script_condition(in string name, in ptr default_settings, out string properties_signal_name, out string trigger_signal_name)
• bool advss_deregister_script_action(in string name)
• bool advss_deregister_script_condition(in string name)
• bool advss_get_variable_value(in string name, out string value)
• bool advss_set_variable_value(in string name, in string value)