Properties API Reference (obs_properties_t)

Properties are used to enumerate available settings for a libobs object. Typically this is used to automatically generate user interface widgets, though can be used to enumerate available and/or valid values for specific settings as well.

type obs_properties_t

Properties object (not reference counted).

type obs_property_t

A property object (not reference counted).

#include <obs.h>

General Functions

obs_properties_t *obs_properties_create(void)
Returns:

A new properties object.

obs_properties_t *obs_properties_create_param(void *param, void (*destroy)(void *param))

Creates a new properties object with specific private data param associated with the object, and is automatically freed with the object when the properties are destroyed via the destroy function.

Returns:

A new properties object.

void obs_properties_destroy(obs_properties_t *props)
void obs_properties_set_flags(obs_properties_t *props, uint32_t flags)
uint32_t obs_properties_get_flags(obs_properties_t *props)
Parameters:

  • flags –

    0 or a bitwise OR combination of one of the following values:

    • OBS_PROPERTIES_DEFER_UPDATE - A hint that tells the front-end to defers updating the settings until the user has finished editing all properties rather than immediately updating any settings

void obs_properties_set_param(obs_properties_t *props, void *param, void (*destroy)(void *param))
void *obs_properties_get_param(obs_properties_t *props)

Sets custom data associated with this properties object. If private data is already associated with the object, that private data will be destroyed before assigning new private data to it.

void obs_properties_apply_settings(obs_properties_t *props, obs_data_t *settings)

Applies settings to the properties by calling all the necessary modification callbacks

obs_properties_t *obs_properties_get_parent(obs_properties_t *props)
void obs_properties_remove_by_name(obs_properties_t *props, const char *property)

Removes a property from a properties list. Only valid in get_properties, script_properties for scripts, modified_callback, and modified_callback2. modified_callback and modified_callback2 must return true so that all UI properties are rebuilt. Returning false is undefined behavior.

Parameters:

  • props – Properties to remove from.

  • property – Name of the property to remove.

Property Object Functions

obs_property_t *obs_properties_add_bool(obs_properties_t *props, const char *name, const char *description)

Adds a boolean property.

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

Returns:

The property

obs_property_t *obs_properties_add_int(obs_properties_t *props, const char *name, const char *description, int min, int max, int step)

Adds an integer property.

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • min – Minimum value

  • max – Maximum value

  • step – Step value

Returns:

The property

obs_property_t *obs_properties_add_float(obs_properties_t *props, const char *name, const char *description, double min, double max, double step)
Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • min – Minimum value

  • max – Maximum value

  • step – Step value

Returns:

The property

obs_property_t *obs_properties_add_int_slider(obs_properties_t *props, const char *name, const char *description, int min, int max, int step)
Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • min – Minimum value

  • max – Maximum value

  • step – Step value

Returns:

The property

obs_property_t *obs_properties_add_float_slider(obs_properties_t *props, const char *name, const char *description, double min, double max, double step)
Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • min – Minimum value

  • max – Maximum value

  • step – Step value

Returns:

The property

obs_property_t *obs_properties_add_text(obs_properties_t *props, const char *name, const char *description, enum obs_text_type type)
Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • type –

    Can be one of the following values:

    • OBS_TEXT_DEFAULT - Single line of text

    • OBS_TEXT_PASSWORD - Single line of text (passworded)

    • OBS_TEXT_MULTILINE - Multi-line text

    • OBS_TEXT_INFO - Read-only informative text, behaves differently depending on wether description, string value and long description are set

Returns:

The property

Important Related Functions:

obs_property_t *obs_properties_add_path(obs_properties_t *props, const char *name, const char *description, enum obs_path_type type, const char *filter, const char *default_path)

Adds a ‘path’ property. Can be a directory or a file.

If target is a file path, the filters should be this format, separated by double semicolons, and extensions separated by space:

"Example types 1 and 2 (*.ex1 *.ex2);;Example type 3 (*.ex3)"
Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • type –

    Can be one of the following values:

    • OBS_PATH_FILE - File (for reading)

    • OBS_PATH_FILE_SAVE - File (for writing)

    • OBS_PATH_DIRECTORY - Directory

  • filter – If type is a file path, then describes the file filter that the user can browse. Items are separated via double semicolons. If multiple file types in a filter, separate with space.

  • default_path – The default path to start in, or NULL

Returns:

The property

obs_property_t *obs_properties_add_list(obs_properties_t *props, const char *name, const char *description, enum obs_combo_type type, enum obs_combo_format format)

Adds an integer/string/floating point item list. This would be implemented as a combo box in user interface.

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • type –

    Can be one of the following values:

    • OBS_COMBO_TYPE_EDITABLE - Can be edited. Only used with string lists.

    • OBS_COMBO_TYPE_LIST - Not editable. Displayed as combo box.

    • OBS_COMBO_TYPE_RADIO - Not editable. Displayed as radio buttons.

      Added in version 30.0.

  • format –

    Can be one of the following values:

    • OBS_COMBO_FORMAT_INT - Integer list

    • OBS_COMBO_FORMAT_FLOAT - Floating point list

    • OBS_COMBO_FORMAT_STRING - String list

    • OBS_COMBO_FORMAT_BOOL - Boolean list

      Added in version 30.0.

Returns:

The property

Important Related Functions:

obs_property_t *obs_properties_add_color(obs_properties_t *props, const char *name, const char *description)

Adds a color property without alpha (stored internally with an alpha value of 255). The color can be retrieved from an obs_data_t object by using obs_data_get_int().

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

Returns:

The property

obs_property_t *obs_properties_add_color_alpha(obs_properties_t *props, const char *name, const char *description)

Adds a color property with alpha. The color can be retrieved from an obs_data_t object by using obs_data_get_int().

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

Returns:

The property

obs_property_t *obs_properties_add_button(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback)
obs_property_t *obs_properties_add_button2(obs_properties_t *props, const char *name, const char *text, obs_property_clicked_t callback, void *priv)

Adds a button property. This property does not actually store any settings; it’s used to implement a button in user interface if the properties are used to generate user interface.

If the properties need to be refreshed due to changes to the property layout, the callback should return true, otherwise return false.

Parameters:

  • name – Setting identifier string

  • text – Localized name shown to user

  • callback – Callback to be executed when the button is pressed

  • priv – Pointer passed back as the data argument of the callback

Returns:

The property

Important Related Functions:

For scripting, use obs_properties_add_button().

Relevant data types used with this function:

typedef bool (*obs_property_clicked_t)(obs_properties_t *props,
                obs_property_t *property, void *data);
obs_property_t *obs_properties_add_font(obs_properties_t *props, const char *name, const char *description)

Adds a font property. The font can be retrieved from an obs_data_t object by using obs_data_get_obj().

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

Returns:

The property

obs_property_t *obs_properties_add_editable_list(obs_properties_t *props, const char *name, const char *description, enum obs_editable_list_type type, const char *filter, const char *default_path)

Adds a list in which the user can add/insert/remove items. The items can be retrieved from an obs_data_t object by using obs_data_get_array().

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • type –

    Can be one of the following values:

    • OBS_EDITABLE_LIST_TYPE_STRINGS - An editable list of strings.

    • OBS_EDITABLE_LIST_TYPE_FILES - An editable list of files.

    • OBS_EDITABLE_LIST_TYPE_FILES_AND_URLS - An editable list of files and URLs.

  • filter – File filter to use if a file list

  • default_path – Default path if a file list

Returns:

The property

obs_property_t *obs_properties_add_frame_rate(obs_properties_t *props, const char *name, const char *description)

Adds a frame rate property.

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

Returns:

The property

Important Related Functions:

obs_property_t *obs_properties_add_group(obs_properties_t *props, const char *name, const char *description, enum obs_group_type type, obs_properties_t *group)

Adds a property group.

Parameters:

  • name – Setting identifier string

  • description – Localized name shown to user

  • type –

    Can be one of the following values:

    • OBS_GROUP_NORMAL - A normal group with just a name and content.

    • OBS_GROUP_CHECKABLE - A checkable group with a checkbox, name and content.

  • group – Group to add

Returns:

The property

Important Related Functions:

Property Enumeration Functions

obs_property_t *obs_properties_first(obs_properties_t *props)
Returns:

The first property in the properties object.

obs_property_t *obs_properties_get(obs_properties_t *props, const char *property)
Parameters:

  • property – The name of the property to get

Returns:

A specific property or NULL if not found

bool obs_property_next(obs_property_t **p)
Parameters:

  • p – Pointer to the pointer of the next property

Returns:

true if successful, false if no more properties

const char *obs_property_name(obs_property_t *p)
Returns:

The setting identifier string of the property

(Author’s Note: “name” was a bad name to use here. Should have been “setting”)

const char *obs_property_description(obs_property_t *p)
Returns:

The actual localized display name of the property

(Author’s note: This one should have been the “name”)

const char *obs_property_long_description(obs_property_t *p)
Returns:

A detailed description of what the setting is used for. Usually used with things like tooltips.

enum obs_property_type obs_property_get_type(obs_property_t *p)
Returns:

One of the following values:

  • OBS_PROPERTY_INVALID

  • OBS_PROPERTY_BOOL

  • OBS_PROPERTY_INT

  • OBS_PROPERTY_FLOAT

  • OBS_PROPERTY_TEXT

  • OBS_PROPERTY_PATH

  • OBS_PROPERTY_LIST

  • OBS_PROPERTY_COLOR

  • OBS_PROPERTY_BUTTON

  • OBS_PROPERTY_FONT

  • OBS_PROPERTY_EDITABLE_LIST

  • OBS_PROPERTY_FRAME_RATE

  • OBS_PROPERTY_GROUP

bool obs_property_enabled(obs_property_t *p)
bool obs_property_visible(obs_property_t *p)
int obs_property_int_min(obs_property_t *p)
int obs_property_int_max(obs_property_t *p)
int obs_property_int_step(obs_property_t *p)
enum obs_number_type obs_property_int_type(obs_property_t *p)
const char *obs_property_int_suffix(obs_property_t *p)
double obs_property_float_min(obs_property_t *p)
double obs_property_float_max(obs_property_t *p)
double obs_property_float_step(obs_property_t *p)
enum obs_number_type obs_property_float_type(obs_property_t *p)
const char *obs_property_float_suffix(obs_property_t *p)
enum obs_text_type obs_property_text_type(obs_property_t *p)
bool obs_property_text_monospace(obs_property_t *p)

Returns whether the input of the text property should be rendered with a monospace font or not. Only has an effect if the text type of the property is OBS_TEXT_MULTILINE, even if this returns true.

enum obs_text_info_type obs_property_text_info_type(obs_property_t *p)
Returns:

One of the following values:

  • OBS_TEXT_INFO_NORMAL

  • OBS_TEXT_INFO_WARNING

  • OBS_TEXT_INFO_ERROR

bool obs_property_text_info_word_wrap(obs_property_t *p)
enum obs_path_type obs_property_path_type(obs_property_t *p)
const char *obs_property_path_filter(obs_property_t *p)
const char *obs_property_path_default_path(obs_property_t *p)
enum obs_combo_type obs_property_list_type(obs_property_t *p)
enum obs_combo_format obs_property_list_format(obs_property_t *p)
bool obs_property_list_item_disabled(obs_property_t *p, size_t idx)
size_t obs_property_list_item_count(obs_property_t *p)
const char *obs_property_list_item_name(obs_property_t *p, size_t idx)
const char *obs_property_list_item_string(obs_property_t *p, size_t idx)
long long obs_property_list_item_int(obs_property_t *p, size_t idx)
double obs_property_list_item_float(obs_property_t *p, size_t idx)
enum obs_editable_list_type obs_property_editable_list_type(obs_property_t *p)
const char *obs_property_editable_list_filter(obs_property_t *p)
const char *obs_property_editable_list_default_path(obs_property_t *p)
size_t obs_property_frame_rate_options_count(obs_property_t *p)
const char *obs_property_frame_rate_option_name(obs_property_t *p, size_t idx)
const char *obs_property_frame_rate_option_description(obs_property_t *p, size_t idx)
size_t obs_property_frame_rate_fps_ranges_count(obs_property_t *p)
struct media_frames_per_second obs_property_frame_rate_fps_range_min(obs_property_t *p, size_t idx)
struct media_frames_per_second obs_property_frame_rate_fps_range_max(obs_property_t *p, size_t idx)
enum obs_button_type obs_property_button_type(obs_property_t *p)
Returns:

One of the following values:

  • OBS_BUTTON_DEFAULT

  • OBS_BUTTON_URL

const char *obs_property_button_url(obs_property_t *p)
enum obs_group_type obs_property_group_type(obs_property_t *p)
Returns:

One of the following values:

  • OBS_COMBO_INVALID

  • OBS_GROUP_NORMAL

  • OBS_GROUP_CHECKABLE

obs_properties_t *obs_property_group_content(obs_property_t *p)

Property Modification Functions

void obs_property_set_modified_callback(obs_property_t *p, obs_property_modified_t modified)
void obs_property_set_modified_callback2(obs_property_t *p, obs_property_modified2_t modified2, void *priv)

Allows the ability to change the properties depending on what settings are used by the user. The callback should return true if the property widgets need to be refreshed due to changes to the property layout.

Relevant data types used with these functions:

typedef bool (*obs_property_modified_t)(obs_properties_t *props,
                obs_property_t *property, obs_data_t *settings);
typedef bool (*obs_property_modified2_t)(void *priv,
                obs_properties_t *props, obs_property_t *property,
                obs_data_t *settings);
bool obs_property_modified(obs_property_t *p, obs_data_t *settings)
bool obs_property_button_clicked(obs_property_t *p, void *obj)
void obs_property_set_visible(obs_property_t *p, bool visible)
void obs_property_set_enabled(obs_property_t *p, bool enabled)
void obs_property_set_description(obs_property_t *p, const char *description)

Sets the displayed localized name of the property, shown to the user.

void obs_property_set_long_description(obs_property_t *p, const char *long_description)

Sets the localized long description of the property, usually shown to a user via tooltip.

void obs_property_int_set_limits(obs_property_t *p, int min, int max, int step)
void obs_property_float_set_limits(obs_property_t *p, double min, double max, double step)
void obs_property_int_set_suffix(obs_property_t *p, const char *suffix)

Adds a suffix to the int property, such that 100 will show up as “100ms” if the suffix is “ms”. The user will only be able to edit the number, not the suffix.

void obs_property_float_set_suffix(obs_property_t *p, const char *suffix)

Adds a suffix to the float property, such that 1.5 will show up as “1.5s” if the suffix is “s”. The user will only be able to edit the number, not the suffix.

void obs_property_text_set_monospace(obs_property_t *p, bool monospace)

Sets whether the input of text property should be rendered with a monospace font or not. Only has an effect if the text type of the property is OBS_TEXT_MULTILINE.

void obs_property_text_set_info_type(obs_property_t *p, enum obs_text_info_type type)
Parameters:

  • type –

    Can be one of the following values:

    • OBS_TEXT_INFO_NORMAL - To show a basic message

    • OBS_TEXT_INFO_WARNING - To show a warning

    • OBS_TEXT_INFO_ERROR - To show an error

void obs_property_text_set_info_word_wrap(obs_property_t *p, bool word_wrap)
void obs_property_list_clear(obs_property_t *p)
size_t obs_property_list_add_string(obs_property_t *p, const char *name, const char *val)

Adds a string to a string list.

Parameters:

  • name – Localized name shown to user

  • val – The actual string value stored and will be returned by obs_data_get_string()

Returns:

The index of the list item.

size_t obs_property_list_add_int(obs_property_t *p, const char *name, long long val)

Adds an integer to a integer list.

Parameters:

  • name – Localized name shown to user

  • val – The actual int value stored and will be returned by obs_data_get_int()

Returns:

The index of the list item.

size_t obs_property_list_add_float(obs_property_t *p, const char *name, double val)

Adds a floating point to a floating point list.

Parameters:

  • name – Localized name shown to user

  • val – The actual float value stored and will be returned by obs_data_get_double()

Returns:

The index of the list item.

void obs_property_list_insert_string(obs_property_t *p, size_t idx, const char *name, const char *val)

Inserts a string in to a string list.

Parameters:

  • idx – The index of the list item

  • name – Localized name shown to user

  • val – The actual string value stored and will be returned by obs_data_get_string()

void obs_property_list_insert_int(obs_property_t *p, size_t idx, const char *name, long long val)

Inserts an integer in to an integer list.

Parameters:

  • idx – The index of the list item

  • name – Localized name shown to user

  • val – The actual int value stored and will be returned by obs_data_get_int()

void obs_property_list_insert_float(obs_property_t *p, size_t idx, const char *name, double val)

Inserts a floating point in to a floating point list.

Parameters:

  • idx – The index of the list item.

  • name – Localized name shown to user

  • val – The actual float value stored and will be returned by obs_data_get_double()

void obs_property_list_item_disable(obs_property_t *p, size_t idx, bool disabled)
void obs_property_list_item_remove(obs_property_t *p, size_t idx)
size_t obs_property_frame_rate_option_add(obs_property_t *p, const char *name, const char *description)
size_t obs_property_frame_rate_fps_range_add(obs_property_t *p, struct media_frames_per_second min, struct media_frames_per_second max)
void obs_property_frame_rate_clear(obs_property_t *p)
void obs_property_frame_rate_options_clear(obs_property_t *p)
void obs_property_frame_rate_fps_ranges_clear(obs_property_t *p)
void obs_property_frame_rate_option_insert(obs_property_t *p, size_t idx, const char *name, const char *description)
void obs_property_frame_rate_fps_range_insert(obs_property_t *p, size_t idx, struct media_frames_per_second min, struct media_frames_per_second max)
void obs_property_button_set_type(obs_property_t *p, enum obs_button_type type)
Parameters:

  • type –

    Can be one of the following values:

    • OBS_BUTTON_DEFAULT - Standard button

    • OBS_BUTTON_URL - Button that opens a URL

Returns:

The property

void obs_property_button_set_url(obs_property_t *p, char *url)