321 lines
10 KiB
ReStructuredText
321 lines
10 KiB
ReStructuredText
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 :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.**
|
|
|
|
|
|
Script Function Exports
|
|
-----------------------
|
|
|
|
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.
|
|
|
|
|
|
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:
|
|
|
|
.. py:function:: script_path()
|
|
|
|
:return: The path to the script.
|
|
|
|
|
|
.. _scripting_timers:
|
|
|
|
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).
|
|
|
|
.. 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)
|
|
|
|
|
|
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
|
|
:c:type:`obs_source_info` structure:
|
|
|
|
.. code:: lua
|
|
|
|
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_script_differences:
|
|
|
|
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).
|
|
|
|
.. 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_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.
|