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 :ref:`other_script_differences` 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.
There are a number of global functions that scripts can optionally provide:
.. py:function:: 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. :param settings: Settings associated with the script.
.. py:function:: script_unload() Called when the script is being unloaded.
.. py:function:: 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. :param settings: Settings associated with the script.
.. py:function:: script_defaults(settings) Called to set default settings (if any) associated with the script. You would typically call :ref:`obs_data_default_funcs` for the on the settings in order to set its default values. :param settings: Settings associated with the script.
.. py:function:: script_update(settings) Called when the script's settings (if any) have been changed by the user. :param settings: Settings associated with the script.
.. py:function:: 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.
:return: obs_properties_t object created via
:c:func:`obs_properties_create()`.
.. py:function:: script_tick(seconds) Called every frame in case per-frame processing is needed. If a timer is needed, please use :ref:`scripting_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. :param seconds: Seconds passed since previous frame.
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:
.. py:function:: script_path() :return: The path to the script.
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).
.. py:function:: timer_add(callback, milliseconds)
Adds an timer callback which triggers every *millseconds*.
.. py:function:: timer_remove(callback)
Removes a timer callback. (Note: You can also use
:py:func:`remove_current_callback()` to terminate the timer from the
timer callback)
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 :c:type:`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)Certain functions are implemented differently from the C API due to how callbacks work. (These functions are part of the obspython/obslua modules/namespaces).
.. py:function:: obs_enum_sources()
Enumerates all sources.
:return: An array of reference-incremented sources. Release with
:py:func:`source_list_release()`.
.. py:function:: obs_scene_enum_items(scene)
Enumerates scene items within a scene.
:param scene: obs_scene_t object to enumerate items from.
:return: List of scene items. Release with
:py:func:`sceneitem_list_release()`.
.. py:function:: obs_sceneitem_group_enum_items(group)
Enumerates scene items within a group.
:param group: obs_sceneitem_t object to enumerate items from.
:return: List of scene items. Release with
:py:func:`sceneitem_list_release()`.
.. py:function:: obs_add_main_render_callback(callback)
**Lua only:** Adds a primary output render callback. This callback
has no parameters.
:param callback: Render callback. Use
:py:func:`obs_remove_main_render_callback()` or
:py:func:`remove_current_callback()` to remove the
callback.
.. py:function:: obs_remove_main_render_callback(callback) **Lua only:** Removes a primary output render callback. :param callback: Render callback.
.. py:function:: 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.
:param handler: A signal_handler_t object.
:param signal: The signal on the signal handler (string)
:param callback: The callback to connect to the signal. Use
:py:func:`signal_handler_disconnect()` or
:py:func:`remove_current_callback()` to remove the
callback.
.. py:function:: signal_handler_disconnect(handler, signal, callback) Removes a callback from a specific signal of a signal handler. :param handler: A signal_handler_t object. :param signal: The signal on the signal handler (string) :param callback: The callback to disconnect from the signal.
.. py:function:: 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.
:param handler: A signal_handler_t object.
:param callback: The callback to connect. Use
:py:func:`signal_handler_disconnect_global()` or
:py:func:`remove_current_callback()` to remove the
callback.
.. py:function:: signal_handler_disconnect_global(handler, callback) Removes a global callback from a signal handler. :param handler: A signal_handler_t object. :param callback: The callback to disconnect.
.. py:function:: obs_hotkey_register_frontend(name, description, callback)
Adds a frontend hotkey. The callback takes one parameter: a boolean
'pressed' parameter.
:param name: Unique name identifier string of the hotkey.
:param description: Hotkey description shown to the user.
:param callback: Callback for the hotkey. Use
:py:func:`obs_hotkey_unregister()` or
:py:func:`remove_current_callback()` to remove
the callback.
.. py:function:: obs_hotkey_unregister(callback) Unregisters the hotkey associated with the specified callback. :param callback: Callback of the hotkey to unregister.
.. py:function:: 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.
:param properties: An obs_properties_t object.
:param setting_name: A setting identifier string.
:param text: Button text.
:param callback: Button callback. This callback is automatically
cleaned up.
.. py:function:: remove_current_callback() Removes the current callback being executed. Does nothing if not within a callback.
.. py:function:: source_list_release(source_list) Releases the references of a source list. :param source_list: Array of sources to release.
.. py:function:: sceneitem_list_release(item_list) Releases the references of a scene item list. :param item_list: Array of scene items to release.
.. py:function:: calldata_source(calldata, name) Casts a pointer parameter of a calldata_t object to an obs_source_t object. :param calldata: A calldata_t object. :param name: Name of the parameter. :return: A borrowed reference to an obs_source_t object.
.. py:function:: calldata_sceneitem(calldata, name) Casts a pointer parameter of a calldata_t object to an obs_sceneitem_t object. :param calldata: A calldata_t object. :param name: Name of the parameter. :return: A borrowed reference to an obs_sceneitem_t object.