From e16ff2db311e9ce199925b00b160414eca9299d2 Mon Sep 17 00:00:00 2001 From: jp9000 Date: Tue, 2 Jan 2018 14:18:41 -0800 Subject: [PATCH] docs/sphinx: Add scripting documentation --- docs/sphinx/index.rst | 1 + docs/sphinx/reference-settings.rst | 5 + docs/sphinx/scripting.rst | 320 +++++++++++++++++++++++++++++ 3 files changed, 326 insertions(+) create mode 100644 docs/sphinx/scripting.rst diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index b874cb4c3..fd1008d73 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -15,6 +15,7 @@ Welcome to OBS Studio's documentation! plugins frontends graphics + scripting reference-core reference-modules reference-core-objects diff --git a/docs/sphinx/reference-settings.rst b/docs/sphinx/reference-settings.rst index 8a29e3ec4..91cd4ba87 100644 --- a/docs/sphinx/reference-settings.rst +++ b/docs/sphinx/reference-settings.rst @@ -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 ----------------------- diff --git a/docs/sphinx/scripting.rst b/docs/sphinx/scripting.rst new file mode 100644 index 000000000..732a4a21e --- /dev/null +++ b/docs/sphinx/scripting.rst @@ -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.