mirror of
https://github.com/obsproject/obs-studio.git
synced 2024-07-04 10:33:30 +00:00
docs/sphinx: Add scripting documentation
This commit is contained in:
parent
190743cf3d
commit
e16ff2db31
|
@ -15,6 +15,7 @@ Welcome to OBS Studio's documentation!
|
|||
plugins
|
||||
frontends
|
||||
graphics
|
||||
scripting
|
||||
reference-core
|
||||
reference-modules
|
||||
reference-core-objects
|
||||
|
|
|
@ -140,6 +140,8 @@ Set Functions
|
|||
---------------------
|
||||
|
||||
|
||||
.. _obs_data_get_funcs:
|
||||
|
||||
Get Functions
|
||||
-------------
|
||||
|
||||
|
@ -171,6 +173,9 @@ Get Functions
|
|||
|
||||
---------------------
|
||||
|
||||
|
||||
.. _obs_data_default_funcs:
|
||||
|
||||
Default Value Functions
|
||||
-----------------------
|
||||
|
||||
|
|
320
docs/sphinx/scripting.rst
Normal file
320
docs/sphinx/scripting.rst
Normal file
|
@ -0,0 +1,320 @@
|
|||
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 install Python 3.6 64bit for OBS 64bit
|
||||
(64bit is the default for OBS), or Python 3.6 32bit if using OBS 32bit.
|
||||
Then, in the scripting dialog, you can manually set the path to your
|
||||
Python 3.6 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(source, settings)
|
||||
-- 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.
|
Loading…
Reference in a new issue