Plugins

Almost all custom functionality is added through plugin modules, which are typically dynamic libraries or scripts. The ability to capture and/or output audio/video, make a recording, output to an RTMP stream, encode in x264 are all examples of things that are accomplished via plugin modules.

Plugins can implement sources, outputs, encoders, and services.

Writing your first plugin? We provide a basic template plugin to get you started.

Plugin Module Headers

These are some notable headers commonly used by plugins:

• libobs/obs-module.h – The primary header used for creating plugin modules. This file automatically includes the following files:

  • libobs/obs.h – The main libobs header. This file automatically includes the following files:

    • libobs/obs-source.h – Used for implementing sources in plugin modules

    • libobs/obs-output.h – Used for implementing outputs in plugin modules

    • libobs/obs-encoder.h – Used for implementing encoders in plugin modules

    • libobs/obs-service.h – Used for implementing services in plugin modules

    • libobs/obs-data.h – Used for managing settings for libobs objects

    • libobs/obs-properties.h – Used for generating properties for libobs objects

    • libobs/graphics/graphics.h – Used for graphics rendering

Common Directory Structure and CMakeLists.txt

The common way source files are organized is to have one file for plugin initialization, and then specific files for each individual object you’re implementing. For example, if you were to create a plugin called ‘my-plugin’, you’d have something like my-plugin.c where plugin initialization is done, my-source.c for the definition of a custom source, my-output.c for the definition of a custom output, etc. (This is not a rule of course)

This is an example of a common directory structure for a native plugin module:

my-plugin/data/locale/en-US.ini
my-plugin/CMakeLists.txt
my-plugin/my-plugin.c
my-plugin/my-source.c
my-plugin/my-output.c
my-plugin/my-encoder.c
my-plugin/my-service.c

This would be an example of a common CMakeLists.txt file associated with these files:

# my-plugin/CMakeLists.txt

project(my-plugin)

set(my-plugin_SOURCES
      my-plugin.c
      my-source.c
      my-output.c
      my-encoder.c
      my-service.c)

add_library(my-plugin MODULE
      ${my-plugin_SOURCES})
target_link_libraries(my-plugin
      libobs)

install_obs_plugin_with_data(my-plugin data)

Native Plugin Initialization

To create a native plugin module, you will need to include the libobs/obs-module.h header, use OBS_DECLARE_MODULE() macro, then create a definition of the function obs_module_load(). In your obs_module_load() function, you then register any of your custom sources, outputs, encoders, or services. See the Module API Reference for more information.

The following is an example of my-plugin.c, which would register one object of each type:

/* my-plugin.c */
#include <obs-module.h>

/* Defines common functions (required) */
OBS_DECLARE_MODULE()

/* Implements common ini-based locale (optional) */
OBS_MODULE_USE_DEFAULT_LOCALE("my-plugin", "en-US")

extern struct obs_source_info  my_source;  /* Defined in my-source.c  */
extern struct obs_output_info  my_output;  /* Defined in my-output.c  */
extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */
extern struct obs_service_info my_service; /* Defined in my-service.c */

bool obs_module_load(void)
{
        obs_register_source(&my_source);
        obs_register_output(&my_output);
        obs_register_encoder(&my_encoder);
        obs_register_service(&my_service);
        return true;
}

Sources

Sources are used to render video and/or audio on stream. Things such as capturing displays/games/audio, playing a video, showing an image, or playing audio. Sources can also be used to implement audio and video filters as well as transitions. The libobs/obs-source.h file is the dedicated header for implementing sources. See the Source API Reference (obs_source_t) for more information.

For example, to implement a source object, you need to define an obs_source_info structure and fill it out with information and callbacks related to your source:

/* my-source.c */

[...]

struct obs_source_info my_source {
        .id           = "my_source",
        .type         = OBS_SOURCE_TYPE_INPUT,
        .output_flags = OBS_SOURCE_VIDEO,
        .get_name     = my_source_name,
        .create       = my_source_create,
        .destroy      = my_source_destroy,
        .update       = my_source_update,
        .video_render = my_source_render,
        .get_width    = my_source_width,
        .get_height   = my_source_height
};

Then, in my-plugin.c, you would call obs_register_source() in obs_module_load() to register the source with libobs.

/* my-plugin.c */

[...]

extern struct obs_source_info  my_source;  /* Defined in my-source.c  */

bool obs_module_load(void)
{
        obs_register_source(&my_source);

        [...]

        return true;
}

Some simple examples of sources:

• Synchronous video source: The image source

• Asynchronous video source: The random texture test source

• Audio source: The sine wave test source

• Video filter: The test video filter

• Audio filter: The gain audio filter

Outputs

Outputs allow the ability to output the currently rendering audio/video. Streaming and recording are two common examples of outputs, but not the only types of outputs. Outputs can receive the raw data or receive encoded data. The libobs/obs-output.h file is the dedicated header for implementing outputs. See the Output API Reference (obs_output_t) for more information.

For example, to implement an output object, you need to define an obs_output_info structure and fill it out with information and callbacks related to your output:

/* my-output.c */

[...]

struct obs_output_info my_output {
        .id                   = "my_output",
        .flags                = OBS_OUTPUT_AV | OBS_OUTPUT_ENCODED,
        .get_name             = my_output_name,
        .create               = my_output_create,
        .destroy              = my_output_destroy,
        .start                = my_output_start,
        .stop                 = my_output_stop,
        .encoded_packet       = my_output_data,
        .get_total_bytes      = my_output_total_bytes,
        .encoded_video_codecs = "h264",
        .encoded_audio_codecs = "aac"
};

Then, in my-plugin.c, you would call obs_register_output() in obs_module_load() to register the output with libobs.

/* my-plugin.c */

[...]

extern struct obs_output_info  my_output;  /* Defined in my-output.c  */

bool obs_module_load(void)
{
        obs_register_output(&my_output);

        [...]

        return true;
}

Some examples of outputs:

• Encoded video/audio outputs:

  • The FLV output

  • The FFmpeg muxer output

  • The RTMP stream output

• Raw video/audio outputs:

  • The FFmpeg output

Encoders

Encoders are OBS-specific implementations of video/audio encoders, which are used with outputs that use encoders. x264, NVENC, Quicksync are examples of encoder implementations. The libobs/obs-encoder.h file is the dedicated header for implementing encoders. See the Encoder API Reference (obs_encoder_t) for more information.

For example, to implement an encoder object, you need to define an obs_encoder_info structure and fill it out with information and callbacks related to your encoder:

/* my-encoder.c */

[...]

struct obs_encoder_info my_encoder_encoder = {
        .id             = "my_encoder",
        .type           = OBS_ENCODER_VIDEO,
        .codec          = "h264",
        .get_name       = my_encoder_name,
        .create         = my_encoder_create,
        .destroy        = my_encoder_destroy,
        .encode         = my_encoder_encode,
        .update         = my_encoder_update,
        .get_extra_data = my_encoder_extra_data,
        .get_sei_data   = my_encoder_sei,
        .get_video_info = my_encoder_video_info
};

Then, in my-plugin.c, you would call obs_register_encoder() in obs_module_load() to register the encoder with libobs.

/* my-plugin.c */

[...]

extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */

bool obs_module_load(void)
{
        obs_register_encoder(&my_encoder);

        [...]

        return true;
}

IMPORTANT NOTE: Encoder settings currently have a few expected common setting values that should have a specific naming convention:

• “bitrate” - This value should be used for both video and audio encoders: bitrate, in kilobits.

• “rate_control” - This is a setting used for video encoders. It’s generally expected to have at least a “CBR” rate control. Other common rate controls are “VBR”, “CQP”.

• “keyint_sec” - For video encoders, sets the keyframe interval value, in seconds, or closest possible approximation. (Author’s note: This should have have been “keyint”, in frames.)

Examples of encoders:

• Video encoders:

  • The x264 encoder

  • The FFmpeg NVENC encoder

  • The Quicksync encoder

• Audio encoders:

  • The FFmpeg AAC/Opus encoder

Services

Services are custom implementations of streaming services, which are used with outputs that stream. For example, you could have a custom implementation for streaming to Twitch, and another for YouTube to allow the ability to log in and use their APIs to do things such as get the RTMP servers or control the channel. The libobs/obs-service.h file is the dedicated header for implementing services. See the Service API Reference (obs_service_t) for more information.

(Author’s note: the service API is incomplete as of this writing)

For example, to implement a service object, you need to define an obs_service_info structure and fill it out with information and callbacks related to your service:

/* my-service.c */

[...]

struct obs_service_info my_service_service = {
        .id       = "my_service",
        .get_name = my_service_name,
        .create   = my_service_create,
        .destroy  = my_service_destroy,
        .encode   = my_service_encode,
        .update   = my_service_update,
        .get_url  = my_service_url,
        .get_key  = my_service_key
};

Then, in my-plugin.c, you would call obs_register_service() in obs_module_load() to register the service with libobs.

/* my-plugin.c */

[...]

extern struct obs_service_info my_service; /* Defined in my-service.c */

bool obs_module_load(void)
{
        obs_register_service(&my_service);

        [...]

        return true;
}

The only two existing services objects are the “common RTMP services” and “custom RTMP service” objects in plugins/rtmp-services

Settings

Settings (see libobs/obs-data.h) are used to get or set settings data typically associated with libobs objects, and can then be saved and loaded via Json text. See the Data Settings API Reference (obs_data_t) for more information.

The obs_data_t is the equivalent of a Json object, where it’s a string table of sub-objects, and the obs_data_array_t is similarly used to store an array of obs_data_t objects, similar to Json arrays (though not quite identical).

To create an obs_data_t or obs_data_array_t object, you’d call the obs_data_create() or obs_data_array_create() functions. obs_data_t and obs_data_array_t objects are reference counted, so when you are finished with the object, call obs_data_release() or obs_data_array_release() to release those references. Any time an obs_data_t or obs_data_array_t object is returned by a function, their references are incremented, so you must release those references each time.

To set values for an obs_data_t object, you’d use one of the following functions:

/* Set functions */
EXPORT void obs_data_set_string(obs_data_t *data, const char *name, const char *val);
EXPORT void obs_data_set_int(obs_data_t *data, const char *name, long long val);
EXPORT void obs_data_set_double(obs_data_t *data, const char *name, double val);
EXPORT void obs_data_set_bool(obs_data_t *data, const char *name, bool val);
EXPORT void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj);
EXPORT void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array);

Similarly, to get a value from an obs_data_t object, you’d use one of the following functions:

/* Get functions */
EXPORT const char *obs_data_get_string(obs_data_t *data, const char *name);
EXPORT long long obs_data_get_int(obs_data_t *data, const char *name);
EXPORT double obs_data_get_double(obs_data_t *data, const char *name);
EXPORT bool obs_data_get_bool(obs_data_t *data, const char *name);
EXPORT obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name);
EXPORT obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name);

Unlike typical Json data objects, the obs_data_t object can also set default values. This allows the ability to control what is returned if there is no value assigned to a specific string in an obs_data_t object when that data is loaded from a Json string or Json file. Each libobs object also has a get_defaults callback which allows setting the default settings for the object on creation.

These functions control the default values are as follows:

/* Default value functions. */
EXPORT void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val);
EXPORT void obs_data_set_default_int(obs_data_t *data, const char *name, long long val);
EXPORT void obs_data_set_default_double(obs_data_t *data, const char *name, double val);
EXPORT void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val);
EXPORT void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj);

Properties

Properties (see libobs/obs-properties.h) are used to automatically generate user interface to modify settings for a libobs object (if desired). Each libobs object has a get_properties callback which is used to generate properties. The properties API defines specific properties that are linked to the object’s settings, and the front-end uses those properties to generate widgets in order to allow the user to modify the settings. For example, if you had a boolean setting, you would use obs_properties_add_bool() to allow the user to be able to change that setting. See the Properties API Reference (obs_properties_t) for more information.

An example of this:

static obs_properties_t *my_source_properties(void *data)
{
        obs_properties_t *ppts = obs_properties_create();
        obs_properties_add_bool(ppts, "my_bool",
                        obs_module_text("MyBool"));
        UNUSED_PARAMETER(data);
        return ppts;
}

[...]

struct obs_source_info my_source {
        .get_properties = my_source_properties,
        [...]
};

The data parameter is the object’s data if the object is present. Typically this is unused and probably shouldn’t be used if possible. It can be null if the properties are retrieved without an object associated with it.

Properties can also be modified depending on what settings are shown. For example, you can mark certain properties as disabled or invisible depending on what a particular setting is set to using the obs_property_set_modified_callback() function.

For example, if you wanted boolean property A to hide text property B:

static bool setting_a_modified(obs_properties_t *ppts,
                obs_property_t *p, obs_data_t *settings)
{
        bool enabled = obs_data_get_bool(settings, "setting_a");
        p = obs_properties_get(ppts, "setting_b");
        obs_property_set_enabled(p, enabled);

        /* return true to update property widgets, false
           otherwise */
        return true;
}

[...]

static obs_properties_t *my_source_properties(void *data)
{
        obs_properties_t *ppts = obs_properties_create();
        obs_property_t *p;

        p = obs_properties_add_bool(ppts, "setting_a",
                        obs_module_text("SettingA"));
        obs_property_set_modified_callback(p, setting_a_modified);

        obs_properties_add_text(ppts, "setting_b",
                        obs_module_text("SettingB"),
                        OBS_TEXT_DEFAULT);
        return ppts;
}

Localization

Typically, most plugins bundled with OBS Studio will use a simple ini-file localization method, where each file is a different language. When using this method, the OBS_MODULE_USE_DEFAULT_LOCALE() macro is used which will automatically load/destroy the locale data with no extra effort on part of the plugin. Then the obs_module_text() function (which is automatically declared as an extern by libobs/obs-module.h) is used when text lookup is needed.

There are two exports the module used to load/destroy locale: the obs_module_set_locale() export, and the obs_module_free_locale() export. The obs_module_set_locale() export is called by libobs to set the current language, and then the obs_module_free_locale() export is called by libobs on destruction of the module. If you wish to implement a custom locale implementation for your plugin, you’d want to define these exports along with the obs_module_text() extern yourself instead of relying on the OBS_MODULE_USE_DEFAULT_LOCALE() macro.