OBS Studio Python Scripting Reference

You can share data between different scripts or plugins using OBS private data. This allows one script to write a value that another script can later retrieve.

Writing Data (Python)

Use S.obs_data_create(), set the value using the appropriate obs_data_set_<type> function, and then call S.obs_apply_private_data(settings) to commit it.

Reading Data (Python)

It is recommended to use a context manager to handle the lifecycle of the private data settings. Retrieve the data using S.obs_get_private_data() and the corresponding obs_data_get_<type> function, ensuring you call S.obs_data_release(settings) when finished.

Writing Data (Lua)

In Lua, create settings with S.obs_data_create(), set the value (e.g., S.obs_data_set_int), apply it with S.obs_apply_private_data(settings), and release the settings.

# Writing in Python
def send_to_private_data(data_type, field, result):
    settings = S.obs_data_create()
    set_func = getattr(obs, f"obs_data_set_{data_type}")
    set_func(settings, field, result)
    S.obs_apply_private_data(settings)
    S.obs_data_release(settings)

# Reading in Python
@contextmanager
def p_data_ar(data_type, field):
    settings = S.obs_get_private_data()
    get_func = getattr(obs, f"obs_data_get_{data_type}")
    try:
        yield get_func(settings, field)
    finally:
        S.obs_data_release(settings)

You can create various UI elements for your script settings using the S.obs_properties_* functions within the script_properties() function. Common property types include:

• Buttons: S.obs_properties_add_button(props, "id", "label", callback)
• Booleans: S.obs_properties_add_bool(props, "id", "label")
• Integers: S.obs_properties_add_int(props, "id", "label", min, max, step)
• Integer Sliders: S.obs_properties_add_int_slider(props, "id", "label", min, max, step)
• Text: S.obs_properties_add_text(props, "id", "label", default_text)
• Color: S.obs_properties_add_color(props, "id", "label")
• Font: S.obs_properties_add_font(props, "id", "label")

Use S.obs_property_set_long_description(property, description) to add a detailed description to a property.

props = S.obs_properties_create()
S.obs_properties_add_button(props, "button1", "Refresh1:", callback)
S.obs_properties_add_bool(props, "_bool", "_bool:")
S.obs_properties_add_int(props, "_int", "_int:", 1, 100, 1)
S.obs_properties_add_int_slider(props, "_slider", "_slider:", 1, 100, 1)
S.obs_properties_add_text(props, "_text", "_text:", S.OBS_TEXT_DEFAULT)
S.obs_properties_add_color(props, "_color", "_color:")
S.obs_properties_add_font(props, "_font", "_font:")

When writing complex OBS scripts, you can use a Python class to maintain state (like a target source name) and encapsulate logic. This allows you to separate the script's internal state from the global OBS script lifecycle functions like script_update or script_properties.

Key lifecycle functions used in this pattern:

• script_description(): Returns a string describing the script.
• script_update(settings): Called when script settings change. Use this to update your class instance state and manage timers.
• script_properties(): Defines the UI elements shown in the OBS Scripts window.

To manage recurring tasks, use S.timer_add(callback, interval_ms) and S.timer_remove(callback) within script_update to ensure timers are correctly restarted when settings change.

import obspython as S

class Example:
    def __init__(self, source_name=None):
        self.source_name = source_name

    def update_text(self):
        source = S.obs_get_source_by_name(self.source_name)
        if source is not None:
            # Logic to update source settings
            settings = S.obs_data_create()
            S.obs_data_set_string(settings, "text", "new_value")
            S.obs_source_update(source, settings)
            S.obs_data_release(settings)
            S.obs_source_release(source)

# Global instance
eg = Example()

def script_update(settings):
    eg.source_name = S.obs_data_get_string(settings, "source")
    S.timer_remove(eg.update_text)
    if eg.source_name != "":
        S.timer_add(eg.update_text, 1000)

def script_properties():
    props = S.obs_properties_create()
    # Add UI properties here
    return props

OBS scripts rely on specific lifecycle hooks to manage properties, settings updates, and initialization. When writing a script, implement the following functions:

• script_properties(): Returns an obs_properties_t object created via S.obs_properties_create(). This defines the UI elements (like text fields or buttons) visible in the script settings.
• script_update(settings): Called when settings are changed in the UI. Use this to extract values from the settings object (e.g., via S.obs_data_get_string) and update your script's internal state.
• script_load(settings): Called when the script is loaded. Use this for initialization, such as setting up hotkeys or loading initial configuration.
• script_save(settings): Called when the script settings are saved. Use this to persist custom data or hotkey bindings to the settings object.

import obspython as S

def script_properties():
    props = S.obs_properties_create()
    S.obs_properties_add_text(props, "_text1", "Label:", S.OBS_TEXT_DEFAULT)
    return props

def script_update(settings):
    val = S.obs_data_get_string(settings, "_text1")
    # Update internal state with val

def script_load(settings):
    # Initialize resources
    pass

def script_save(settings):
    # Persist data
    pass

To implement hotkeys that persist across OBS sessions, you must register the hotkey using obs_hotkey_register_frontend, load the previously saved key from the script settings, and save the key back to the settings when the script is saved.

1. Register: Use S.obs_hotkey_register_frontend(id, description, callback) to create the hotkey.
2. Load: Retrieve the saved key array from the settings using S.obs_data_get_array(settings, id) and apply it with S.obs_hotkey_load(hotkey_id, key_array).
3. Save: Capture the current key using S.obs_hotkey_save(hotkey_id) and store it in the settings using S.obs_data_set_array(settings, id, key_array).

Note: Always call S.obs_data_array_release(array) after using an array retrieved from obs_data to prevent memory leaks.

import obspython as S

# Inside your script logic
class Hotkey:
    def __init__(self, callback, obs_settings, _id):
        self.obs_data = obs_settings
        self.hotkey_id = S.OBS_INVALID_HOTKEY_ID
        self.hotkey_saved_key = None
        self.callback = callback
        self._id = _id

    def register_hotkey(self):
        description = "Hotkey description"
        self.hotkey_id = S.obs_hotkey_register_frontend(
            "htk_id" + str(self._id), description, self.callback
        )
        # Load existing key if available
        if self.hotkey_saved_key:
            S.obs_hotkey_load(self.hotkey_id, self.hotkey_saved_key)

    def save_hotkey(self):
        self.hotkey_saved_key = S.obs_hotkey_save(self.hotkey_id)
        S.obs_data_set_array(
            self.obs_data, "htk_id" + str(self._id), self.hotkey_saved_key
        )
        S.obs_data_array_release(self.hotkey_saved_key)