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_description()
   Called to retrieve a description string to be displayed to the user
   in the Scripts window.

.. 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_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.