obs-studio/docs/sphinx/scripting.rst

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:** On windows, currently only Python 3.6 is supported. To use
Python on windows, you must download and install Python 3.6.x "x86-64"
for OBS 64bit (64bit is the default), or Python 3.6.x "x86" if using OBS
32bit. Then, in the scripting dialog, you must set the path to the
Python 3.6.x 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 properties to an obs_properties_t object. The callback
takes no parameters.
: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.