OBS Studio Frontend API

The OBS Studio frontend API is the API specific to OBS Studio itself.

#include <obs-frontend-api.h>

Structures/Enumerations

enum obs_frontend_event

Specifies a front-end event. Can be one of the following values:

  • OBS_FRONTEND_EVENT_STREAMING_STARTING

    Triggered when streaming is starting.

  • OBS_FRONTEND_EVENT_STREAMING_STARTED

    Triggered when streaming has successfully started.

  • OBS_FRONTEND_EVENT_STREAMING_STOPPING

    Triggered when streaming is stopping.

  • OBS_FRONTEND_EVENT_STREAMING_STOPPED

    Triggered when streaming has fully stopped.

  • OBS_FRONTEND_EVENT_RECORDING_STARTING

    Triggered when recording is starting.

  • OBS_FRONTEND_EVENT_RECORDING_STARTED

    Triggered when recording has successfully started.

  • OBS_FRONTEND_EVENT_RECORDING_STOPPING

    Triggered when recording is stopping.

  • OBS_FRONTEND_EVENT_RECORDING_STOPPED

    Triggered when recording has fully stopped.

  • OBS_FRONTEND_EVENT_RECORDING_PAUSED

    Triggered when the recording has been paused.

  • OBS_FRONTEND_EVENT_RECORDING_UNPAUSED

    Triggered when the recording has been unpaused.

  • OBS_FRONTEND_EVENT_SCENE_CHANGED

    Triggered when the current scene has changed.

  • OBS_FRONTEND_EVENT_SCENE_LIST_CHANGED

    Triggered when a scenes has been added/removed/reordered by the user.

  • OBS_FRONTEND_EVENT_TRANSITION_CHANGED

    Triggered when the current transition has changed by the user.

  • OBS_FRONTEND_EVENT_TRANSITION_STOPPED

    Triggered when a transition has completed.

  • OBS_FRONTEND_EVENT_TRANSITION_LIST_CHANGED

    Triggered when the user adds/removes transitions.

  • OBS_FRONTEND_EVENT_TRANSITION_DURATION_CHANGED

    Triggered when the transition duration has been changed by the

    user.

  • OBS_FRONTEND_EVENT_TBAR_VALUE_CHANGED

    Triggered when the transition bar is moved.

  • OBS_FRONTEND_EVENT_SCENE_COLLECTION_CHANGING

    Triggered when the current scene collection is about to change.

  • OBS_FRONTEND_EVENT_SCENE_COLLECTION_CHANGED

    Triggered when the current scene collection has changed.

  • OBS_FRONTEND_EVENT_SCENE_COLLECTION_LIST_CHANGED

    Triggered when a scene collection has been added or removed.

  • OBS_FRONTEND_EVENT_SCENE_COLLECTION_RENAMED

    Triggered when a scene collection has been renamed.

  • OBS_FRONTEND_EVENT_PROFILE_CHANGING

    Triggered when the current profile is about to change.

  • OBS_FRONTEND_EVENT_PROFILE_CHANGED

    Triggered when the current profile has changed.

  • OBS_FRONTEND_EVENT_PROFILE_LIST_CHANGED

    Triggered when a profile has been added or removed.

  • OBS_FRONTEND_EVENT_PROFILE_RENAMED

    Triggered when a profile has been renamed.

  • OBS_FRONTEND_EVENT_FINISHED_LOADING

    Triggered when the program has finished loading.

  • OBS_FRONTEND_EVENT_SCRIPTING_SHUTDOWN

    Triggered when scripts need to know that OBS is exiting. The OBS_FRONTEND_EVENT_EXIT event is normally called after scripts have been destroyed.

  • OBS_FRONTEND_EVENT_EXIT

    Triggered when the program is about to exit.

  • OBS_FRONTEND_EVENT_REPLAY_BUFFER_STARTING

    Triggered when the replay buffer is starting.

  • OBS_FRONTEND_EVENT_REPLAY_BUFFER_STARTED

    Triggered when the replay buffer has successfully started.

  • OBS_FRONTEND_EVENT_REPLAY_BUFFER_STOPPING

    Triggered when the replay buffer is stopping.

  • OBS_FRONTEND_EVENT_REPLAY_BUFFER_STOPPED

    Triggered when the replay buffer has fully stopped.

  • OBS_FRONTEND_EVENT_REPLAY_BUFFER_SAVED

    Triggered when the replay buffer has been saved.

  • OBS_FRONTEND_EVENT_STUDIO_MODE_ENABLED

    Triggered when the user has turned on studio mode.

  • OBS_FRONTEND_EVENT_STUDIO_MODE_DISABLED

    Triggered when the user has turned off studio mode.

  • OBS_FRONTEND_EVENT_PREVIEW_SCENE_CHANGED

    Triggered when the current preview scene has changed in studio mode.

  • OBS_FRONTEND_EVENT_SCENE_COLLECTION_CLEANUP

    Triggered when a scene collection has been completely unloaded, and the program is either about to load a new scene collection, or the program is about to exit.

  • OBS_FRONTEND_EVENT_VIRTUALCAM_STARTED

    Triggered when the virtual camera is started.

  • OBS_FRONTEND_EVENT_VIRTUALCAM_STOPPED

    Triggered when the virtual camera is stopped.

struct obs_frontend_source_list

  • DARRAY(obs_source_t*) sources

Example usage:

struct obs_frontend_source_list scenes = {0};

obs_frontend_get_scenes(&scenes);

for (size_t i = 0; i < scenes.num; i++) {
        obs_source_t *source = scenes.sources.array[i];

        [...]
}

obs_frontend_source_list_free(&scenes);
typedef void (*obs_frontend_cb)(void *private_data)

Frontend tool menu callback

typedef void (*obs_frontend_event_cb)(enum obs_frontend_event event, void *private_data)

Frontend event callback

typedef void (*obs_frontend_save_cb)(obs_data_t *save_data, bool saving, void *private_data)

Frontend save/load callback

typedef bool (*obs_frontend_translate_ui_cb)(const char *text, const char **out)

Translation callback

Functions

void obs_frontend_source_list_free(struct obs_frontend_source_list *source_list)

Releases sources within a source list and frees the list.

Parameters

  • source_list – Source list to free

void *obs_frontend_get_main_window(void)
Returns

The QMainWindow pointer to the OBS Studio window

void *obs_frontend_get_main_window_handle(void)
Returns

The native window handle of the OBS Studio window

char **obs_frontend_get_scene_names(void)
Returns

The scene name list, ending with NULL. The list is stored within one contiguous segment of memory, so freeing the returned pointer with bfree() will free the entire list.

void obs_frontend_get_scenes(struct obs_frontend_source_list *sources)
Parameters
obs_source_t *obs_frontend_get_current_scene(void)
Returns

A new reference to the currently active scene

void obs_frontend_set_current_scene(obs_source_t *scene)
Parameters

  • scene – The scene to set as the current scene

void obs_frontend_get_transitions(struct obs_frontend_source_list *sources)
Parameters
obs_source_t *obs_frontend_get_current_transition(void)
Returns

A new reference to the currently active transition

void obs_frontend_set_current_transition(obs_source_t *transition)
Parameters

  • transition – The transition to set as the current transition

int obs_frontend_get_transition_duration(void)
Returns

The transition duration (in milliseconds) currently set in the UI

void obs_frontend_set_transition_duration(int duration)
Parameters

  • duration – Desired transition duration, in milliseconds

void obs_frontend_release_tbar(void)

Emulate a mouse button release on the transition bar and determine transition status.

void obs_frontend_set_tbar_position(int position)

Set the value of the transition bar.

Parameters

  • position – The position to set the T-bar to, with a range of 0-1023

int obs_frontend_get_tbar_position(void)

Get the value of the transition bar.

Returns

The value of the position of the T-bar to, with a range of 0-1023

char **obs_frontend_get_scene_collections(void)
Returns

The list of profile names, ending with NULL. The list is stored within one contiguous segment of memory, so freeing the returned pointer with bfree() will free the entire list.

char *obs_frontend_get_current_scene_collection(void)
Returns

A new pointer to the current scene collection name. Free with bfree()

void obs_frontend_set_current_scene_collection(const char *collection)
Parameters

  • profile – Name of the scene collection to activate

bool obs_frontend_add_scene_collection(const char *name)

Add a new scene collection, then switch to it.

Parameters

  • name – Name of the scene collection to add/create

char **obs_frontend_get_profiles(void)
Returns

The list of profile names, ending with NULL. The list is stored within one contiguous segment of memory, so freeing the returned pointer with bfree() will free the entire list.

char *obs_frontend_get_current_profile(void)
Returns

A new pointer to the current profile name. Free with bfree()

char *obs_frontend_get_current_profile_path(void)
Returns

A new pointer to the current profile’s path on the filesystem. Free with bfree()

void obs_frontend_set_current_profile(const char *profile)
Parameters

  • profile – Name of the profile to activate

bool obs_frontend_create_profile(const char *name)
Parameters

  • name – Name of the new profile to create (must be unique)

bool obs_frontend_duplicate_profile(const char *name)
Parameters

  • name – Name of the duplicate profile to create (must be unique)

void obs_frontend_delete_profile(const char *profile)
Parameters

  • profile – Name of the profile to delete

void *obs_frontend_add_tools_menu_qaction(const char *name)

Adds a QAction to the tools menu then returns it.

Parameters

  • name – Name for the new menu item

Returns

A pointer to the added QAction

void obs_frontend_add_tools_menu_item(const char *name, obs_frontend_cb callback, void *private_data)

Adds a tools menu item and links the ::clicked signal to the callback.

Parameters

  • name – The name for the new menu item

  • callback – Callback to use when the menu item is clicked

  • private_data – Private data associated with the callback

void *obs_frontend_add_dock(void *dock)

Adds a QDockWidget to the UI’s Docks menu.

Parameters

  • dock – QDockWidget to add/create

Returns

A pointer to the added QAction

void obs_frontend_add_event_callback(obs_frontend_event_cb callback, void *private_data)

Adds a callback that will be called when a frontend event occurs. See obs_frontend_event on what sort of events can be triggered.

Parameters

  • callback – Callback to use when a frontend event occurs

  • private_data – Private data associated with the callback

void obs_frontend_remove_event_callback(obs_frontend_event_cb callback, void *private_data)

Removes an event callback.

Parameters

  • callback – Callback to remove

  • private_data – Private data associated with the callback

void obs_frontend_add_save_callback(obs_frontend_save_cb callback, void *private_data)

Adds a callback that will be called when the current scene collection is being saved/loaded.

Parameters

  • callback – Callback to use when saving/loading a scene collection

  • private_data – Private data associated with the callback

void obs_frontend_remove_save_callback(obs_frontend_save_cb callback, void *private_data)

Removes a save/load callback.

Parameters

  • callback – Callback to remove

  • private_data – Private data associated with the callback

void obs_frontend_add_preload_callback(obs_frontend_save_cb callback, void *private_data)

Adds a callback that will be called right before a scene collection is loaded.

Parameters

  • callback – Callback to use when pre-loading

  • private_data – Private data associated with the callback

void obs_frontend_remove_preload_callback(obs_frontend_save_cb callback, void *private_data)

Removes a pre-load callback.

Parameters

  • callback – Callback to remove

  • private_data – Private data associated with the callback

void obs_frontend_push_ui_translation(obs_frontend_translate_ui_cb translate)

Pushes a UI translation callback. This allows a front-end plugin to intercept when Qt is automatically generating translating data. Typically this is just called with obs_module_get_string.

Parameters

  • translate – The translation callback to use

void obs_frontend_pop_ui_translation(void)

Pops the current UI translation callback.

void obs_frontend_streaming_start(void)

Starts streaming.

void obs_frontend_streaming_stop(void)

Stops streaming.

bool obs_frontend_streaming_active(void)
Returns

true if streaming active, false otherwise

void obs_frontend_recording_start(void)

Starts recording.

void obs_frontend_recording_stop(void)

Stops recording.

bool obs_frontend_recording_active(void)
Returns

true if recording active, false otherwise

void obs_frontend_recording_pause(bool pause)
Pause

true to pause recording, false to unpause

bool obs_frontend_recording_paused(void)
Returns

true if recording paused, false otherwise

void obs_frontend_replay_buffer_start(void)

Starts the replay buffer.

void obs_frontend_replay_buffer_stop(void)

Stops the replay buffer.

void obs_frontend_replay_buffer_save(void)

Saves a replay if the replay buffer is active.

bool obs_frontend_replay_buffer_active(void)
Returns

true if replay buffer active, false otherwise

void obs_frontend_open_projector(const char *type, int monitor, const char *geometry, const char *name)
Parameters

  • type – “Preview”, “Source”, “Scene”, “StudioProgram”, or “Multiview” (case insensitive)

  • monitor – Monitor to open the projector on. If -1, this opens a window.

  • geometry – If monitor is -1, size and position of the projector window. Encoded in Base64 using Qt’s geometry encoding.

  • name – If type is “Source” or “Scene”, name of the source or scene to be displayed

void obs_frontend_save(void)

Saves the current scene collection.

obs_output_t *obs_frontend_get_streaming_output(void)
Returns

A new reference to the current streaming output

obs_output_t *obs_frontend_get_recording_output(void)
Returns

A new reference to the current srecording output

obs_output_t *obs_frontend_get_replay_buffer_output(void)
Returns

A new reference to the current replay buffer output

config_t *obs_frontend_get_profile_config(void)
Returns

The config_t* associated with the current profile

config_t *obs_frontend_get_global_config(void)
Returns

The config_t* associated with the global config (global.ini)

void obs_frontend_set_streaming_service(obs_service_t *service)

Sets the current streaming service to stream with.

Parameters

  • service – The streaming service to set

obs_service_t *obs_frontend_get_streaming_service(void)
Returns

A new reference to the current streaming service object

void obs_frontend_save_streaming_service(void)

Saves the current streaming service data.

bool obs_frontend_preview_program_mode_active(void)
Returns

true if studio mode is active, false otherwise

void obs_frontend_set_preview_program_mode(bool enable)

Activates/deactivates studio mode.

Parameters

  • enable – true to activate studio mode, false to deactivate studio mode

void obs_frontend_preview_program_trigger_transition(void)

Triggers a preview-to-program transition if studio mode is active.

obs_source_t *obs_frontend_get_current_preview_scene(void)
Returns

A new reference to the current preview scene if studio mode is active, or NULL if studio mode is not active.

void obs_frontend_set_current_preview_scene(obs_source_t *scene)

Sets the current preview scene in studio mode. Does nothing if studio mode is disabled.

Parameters

  • scene – The scene to set as the current preview

void obs_frontend_set_preview_enabled(bool enable)

Sets the enable state of the preview display. Only relevant with studio mode disabled.

Parameters

  • enable – true to enable preview, false to disable preview

bool obs_frontend_preview_enabled(void)
Returns

true if the preview display is enabled, false otherwise

void *obs_frontend_take_screenshot(void)

Takes a screenshot of the main OBS output.

void *obs_frontend_take_source_screenshot(obs_source_t *source)

Takes a screenshot of the specified source.

Parameters

  • source – The source to take screenshot of

obs_output_t *obs_frontend_get_virtualcam_output(void)
Returns

A new reference to the current virtual camera output

void obs_frontend_start_virtualcam(void)

Starts the virtual camera.

void obs_frontend_stop_virtualcam(void)

Stops the virtual camera.

bool obs_frontend_virtualcam_active(void)
Returns

true if virtual camera is active, false otherwise

void obs_frontend_reset_video(void)

Reloads the UI canvas and resets libobs video with latest data from the current profile.

void *obs_frontend_open_source_properties(obs_source_t *source)

Opens the properties window of the specified source.

Parameters

  • source – The source to open the properties window of

void *obs_frontend_open_source_filters(obs_source_t *source)

Opens the filters window of the specified source.

Parameters

  • source – The source to open the filters window of

void *obs_frontend_open_source_interaction(obs_source_t *source)

Opens the interact window of the specified source. Only call if source has the OBS_SOURCE_INTERACTION output flag.

Parameters

  • source – The source to open the interact window of

char *obs_frontend_get_current_record_output_path(void)
Returns

A new pointer to the current record output path. Free with bfree()

const char *obs_frontend_get_locale_string(const char *string)
Returns

Gets the frontend translation of a given string.