Module API Reference

Modules add custom functionality to libobs: typically Sources, Outputs, Encoders, and Services.

obs_module_t

A module object (not reference counted).

#include <obs-module.h>

Module Macros

These macros are used within custom plugin modules.

OBS_DECLARE_MODULE()

Declares a libobs module. Exports important core module functions related to the module itself, OBS version, etc.


OBS_MODULE_USE_DEFAULT_LOCALE(module_name, default_locale)

Helper macro that uses the standard ini file format for localization. Automatically initializes and destroys localization data, and automatically provides module externs such as obs_module_text() to be able to get a localized string with little effort.


Module Exports

These are functions that plugin modules can optionally export in order to communicate with libobs and front-ends.

bool obs_module_load(void)

Required: Called when the module is loaded. Implement this function to load all the sources/encoders/outputs/services for your module, or anything else that may need loading.

Returns

Return true to continue loading the module, otherwise false to indicate failure and unload the module


void obs_module_unload(void)

Optional: Called when the module is unloaded.


void obs_module_post_load(void)

Optional: Called when all modules have finished loading.


void obs_module_set_locale(const char *locale)

Called to set the locale language and load the locale data for the module.


void obs_module_free_locale(void)

Called on module destruction to free locale data.


const char *obs_module_name(void)

(Optional)

Returns

The full name of the module


const char *obs_module_description(void)

(Optional)

Returns

A description of the module


Module Externs

These functions are externs that are usable throughout the module.

const char *obs_module_text(const char *lookup_string)
Returns

A localized string


bool obs_module_get_string(const char *lookup_string, const char **translated_string)

Helper function for looking up locale.

Returns

true if text found, otherwise false


obs_module_t *obs_current_module(void)
Returns

The current module


char *obs_module_file(const char *file)

Returns the location to a module data file associated with the current module. Free with bfree() when complete.

Equivalent to:

obs_find_module_file(obs_current_module(), file);

char *obs_module_config_path(const char *file)

Returns the location to a module config file associated with the current module. Free with bfree() when complete. Will return NULL if configuration directory is not set.

Equivalent to:

obs_module_get_config_path(obs_current_module(), file);

Frontend Module Functions

These are functions used by frontends to load and get information about plugin modules.

int obs_open_module(obs_module_t **module, const char *path, const char *data_path)

Opens a plugin module directly from a specific path.

If the module already exists then the function will return successful, and the module parameter will be given the pointer to the existing module.

This does not initialize the module, it only loads the module image. To initialize the module, call obs_init_module().

Parameters
  • module – The pointer to the created module

  • path – Specifies the path to the module library file. If the extension is not specified, it will use the extension appropriate to the operating system

  • data_path – Specifies the path to the directory where the module’s data files are stored (or NULL if none)

Returns

MODULE_SUCCESS - Successful
MODULE_ERROR - A generic error occurred
MODULE_FILE_NOT_FOUND - The module was not found
MODULE_MISSING_EXPORTS - Required exports are missing
MODULE_INCOMPATIBLE_VER - Incompatible version


bool obs_init_module(obs_module_t *module)

Initializes the module, which calls its obs_module_load export.

Returns

true if the module was loaded successfully


void obs_log_loaded_modules(void)

Logs loaded modules.


const char *obs_get_module_file_name(obs_module_t *module)
Returns

The module file name


const char *obs_get_module_name(obs_module_t *module)
Returns

The module full name (or NULL if none)


void obs_get_module_author(obs_module_t *module)
Returns

The module author(s)


const char *obs_get_module_description(obs_module_t *module)
Returns

The module description


const char *obs_get_module_binary_path(obs_module_t *module)
Returns

The module binary path


const char *obs_get_module_data_path(obs_module_t *module)
Returns

The module data path


void obs_add_module_path(const char *bin, const char *data)

Adds a module search path to be used with obs_find_modules. If the search path strings contain %module%, that text will be replaced with the module name when used.

Parameters
  • bin – Specifies the module’s binary directory search path

  • data – Specifies the module’s data directory search path


void obs_load_all_modules(void)

Automatically loads all modules from module paths (convenience function).


void obs_post_load_modules(void)

Notifies modules that all modules have been loaded.


void obs_find_modules(obs_find_module_callback_t callback, void *param)

Finds all modules within the search paths added by obs_add_module_path().

Relevant data types used with this function:

struct obs_module_info {
        const char *bin_path;
        const char *data_path;
};

typedef void (*obs_find_module_callback_t)(void *param,
                const struct obs_module_info *info);

void obs_enum_modules(obs_enum_module_callback_t callback, void *param)

Enumerates all loaded modules.

Relevant data types used with this function:

typedef void (*obs_enum_module_callback_t)(void *param, obs_module_t *module);

char *obs_find_module_file(obs_module_t *module, const char *file)

Returns the location of a plugin module data file.

Note: Modules should use obs_module_file function defined in obs-module.h

as a more elegant means of getting their files without having to specify the module parameter.

Parameters
  • module – The module associated with the file to locate

  • file – The file to locate

Returns

Path string, or NULL if not found. Use bfree to free string


char *obs_module_get_config_path(obs_module_t *module, const char *file)

Returns the path of a plugin module config file (whether it exists or not).

Note: Modules should use obs_module_config_path function defined in

obs-module.h as a more elegant means of getting their files without having to specify the module parameter.

Parameters
  • module – The module associated with the path

  • file – The file to get a path to

Returns

Path string, or NULL if not found. Use bfree to free string