Python/Lua Scripting

Scripting (21.0+) adds support for Python 3 and Luajit 2 (which is roughly equivalent to Lua 5.2), allowing the ability to quickly extend, add features, or automate the program without needing to build a native plugin module.

Scripting can be accessed in OBS Studio via the Tools menu -> Scripts option, which will bring up the scripting dialog. Scripts can be added, removed, and reloaded in real time while the program is running.

NOTE: To use Python on Windows or macOS, you must download and install a Python version that matches your OBS architecture. Then, in the scripting dialog, you must set the path to the Python install in the “Python Settings” tab.

All API bindings are provided through the obspython module in Python, and the obslua module in Lua.

Certain functions have been changed/replaced in order to provide script callbacks, see Other Differences From the C API for more information.

WARNING: Because bindings to the entire API are provided, it is possible to leak memory or crash the program with an improperly-written script. Please exercise caution when making scripts and check the memory leak counter in your log file to make sure scripts you write aren’t leaking memory. Please treat the API bindings as though you were writing a C program: read the documentation for functions you use, and release/destroy objects you reference or create via the API.

Script Function Exports

There are a number of global functions that scripts can optionally provide:

script_description(): Called to retrieve a description string to be displayed to the user in the Scripts window.

script_load(settings)

Called on script startup with specific settings associated with the script. The settings parameter provided is not typically used for settings that are set by the user; instead the parameter is used for any extra internal settings data that may be used in the script.

Parameters:: settings – Settings associated with the script.

script_unload(): Called when the script is being unloaded.

script_save(settings)

Called when the script is being saved. This is not necessary for settings that are set by the user; instead this is used for any extra internal settings data that may be used in the script.

Parameters:: settings – Settings associated with the script.

script_defaults(settings)

Called to set default settings (if any) associated with the script. You would typically call Default Value Functions for the on the settings in order to set its default values.

Parameters:: settings – Settings associated with the script.

script_update(settings)

Called when the script’s settings (if any) have been changed by the user.

Parameters:: settings – Settings associated with the script.

script_properties()

Called to define user properties associated with the script. These properties are used to define how to show settings properties to a user.

Returns:: obs_properties_t object created via obs_properties_create().

script_tick(seconds)

Called every frame in case per-frame processing is needed. If a timer is needed, please use Script Timers instead, as timers are more efficient if all that’s needed is basic timer functionality. Using this function in Python is not recommended due to the global interpreter lock of Python.

Parameters:: seconds – Seconds passed since previous frame.

Getting the Current Script’s Path

There is a function you can use to get the current script’s path. This function is automatically implemented in to each script before the script is loaded, and is part of the script’s namespace, not obslua/obspython:

script_path()

Returns:: The path to the script.

Script Timers

Script timers provide an efficient means of providing timer callbacks without necessarily having to lock scripts/interpreters every frame. (These functions are part of the obspython/obslua modules/namespaces).

timer_add(callback, milliseconds)

Adds an timer callback which triggers every milliseconds.

Note: Using instance methods as callbacks is not supported. Always use module methods.

timer_remove(callback): Removes a timer callback. (Note: You can also use remove_current_callback() to terminate the timer from the timer callback)

Script Sources (Lua Only)

It is possible to register sources in Lua. To do so, create a table, and define its keys the same way you would define an obs_source_info structure:

local info = {}
info.id = "my_source_id"
info.type = obslua.OBS_SOURCE_TYPE_INPUT
info.output_flags = obslua.OBS_SOURCE_VIDEO

info.get_name = function()
        return "My Source"
end

info.create = function(settings, source)
        -- typically source data would be stored as a table
        local my_source_data = {}

        [...]

        return my_source_data
end

info.video_render = function(my_source_data, effect)
        [...]
end

info.get_width = function(my_source_data)
        [...]

        -- assuming the source data contains a 'width' key
        return my_source_data.width
end

info.get_height = function(my_source_data)
        [...]

        -- assuming the source data contains a 'height' key
        return my_source_data.height
end

-- register the source
obs_register_source(info)

Other Differences From the C API

Certain functions are implemented differently from the C API due to how callbacks work. (These functions are part of the obspython/obslua modules/namespaces).

obs_enum_sources()

Enumerates all sources.

Returns:: An array of reference-incremented sources. Release with source_list_release().

obs_scene_enum_items(scene)

Enumerates scene items within a scene.

Parameters:: scene – obs_scene_t object to enumerate items from.
Returns:: List of scene items. Release with sceneitem_list_release().

obs_sceneitem_group_enum_items(group)

Enumerates scene items within a group.

Parameters:: group – obs_sceneitem_t object to enumerate items from.
Returns:: List of scene items. Release with sceneitem_list_release().

obs_add_main_render_callback(callback)

Lua only: Adds a primary output render callback. This callback has no parameters.

Parameters:: callback – Render callback. Use obs_remove_main_render_callback() or remove_current_callback() to remove the callback.

obs_remove_main_render_callback(callback)

Lua only: Removes a primary output render callback.

Parameters:: callback – Render callback.

signal_handler_connect(handler, signal, callback)

Adds a callback to a specific signal on a signal handler. This callback has one parameter: the calldata_t object.

Parameters:

handler – A signal_handler_t object.
signal – The signal on the signal handler (string)
callback – The callback to connect to the signal. Use signal_handler_disconnect() or remove_current_callback() to remove the callback.

signal_handler_disconnect(handler, signal, callback)

Removes a callback from a specific signal of a signal handler.

Parameters:

handler – A signal_handler_t object.
signal – The signal on the signal handler (string)
callback – The callback to disconnect from the signal.

signal_handler_connect_global(handler, callback)

Adds a global callback to a signal handler. This callback has two parameters: the first parameter is the signal string, and the second parameter is the calldata_t object.

Parameters:

handler – A signal_handler_t object.
callback – The callback to connect. Use signal_handler_disconnect_global() or remove_current_callback() to remove the callback.

signal_handler_disconnect_global(handler, callback)

Removes a global callback from a signal handler.

Parameters:

handler – A signal_handler_t object.
callback – The callback to disconnect.

obs_hotkey_register_frontend(name, description, callback)

Adds a frontend hotkey. The callback takes one parameter: a boolean ‘pressed’ parameter.

Parameters:

name – Unique name identifier string of the hotkey.
description – Hotkey description shown to the user.
callback – Callback for the hotkey. Use obs_hotkey_unregister() or remove_current_callback() to remove the callback.

obs_hotkey_unregister(callback)

Unregisters the hotkey associated with the specified callback.

Parameters:: callback – Callback of the hotkey to unregister.

obs_properties_add_button(properties, setting_name, text, callback)

Adds a button property to an obs_properties_t object. The callback takes two parameters: the first parameter is the obs_properties_t object, and the second parameter is the obs_property_t for the button.

Parameters:

properties – An obs_properties_t object.
setting_name – A setting identifier string.
text – Button text.
callback – Button callback. This callback is automatically cleaned up.

remove_current_callback(): Removes the current callback being executed. Does nothing if not within a callback.

source_list_release(source_list)

Releases the references of a source list.

Parameters:: source_list – Array of sources to release.

sceneitem_list_release(item_list)

Releases the references of a scene item list.

Parameters:: item_list – Array of scene items to release.

calldata_source(calldata, name)

Casts a pointer parameter of a calldata_t object to an obs_source_t object.

Parameters:

calldata – A calldata_t object.
name – Name of the parameter.

Returns:

A borrowed reference to an obs_source_t object.

calldata_sceneitem(calldata, name)

Casts a pointer parameter of a calldata_t object to an obs_sceneitem_t object.

Parameters:

calldata – A calldata_t object.
name – Name of the parameter.

Returns:

A borrowed reference to an obs_sceneitem_t object.