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. This is the last chance to call any frontend API functions for any saving / cleanup / etc. After returning from this event callback, it is not permitted to make any further frontend API calls.

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

  • OBS_FRONTEND_EVENT_THEME_CHANGED

    Triggered when the theme is changed.

    Added in version 29.0.0.

  • OBS_FRONTEND_EVENT_SCREENSHOT_TAKEN

    Triggered when a screenshot is taken.

    Added in version 29.0.0.

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.sources.num; i++) {
      /* Do NOT call `obs_source_release` or `obs_scene_release`
       * on these sources
       */
      obs_source_t *source = scenes.sources.array[i];

      /* Convert to obs_scene_t if needed */
      obs_scene_t *scene = obs_scene_from_source(source);

      [...]
}

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

typedef void (*undo_redo_cb)(const char *data)

Undo redo 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. The order is same as the way the frontend displays it in the Scenes dock.

void obs_frontend_get_scenes(struct obs_frontend_source_list *sources)

Populates sources with reference-incremented scenes in the same order as the frontend displays it in the Scenes dock. Release with obs_frontend_source_list_free(), which will automatically release all scenes with obs_source_release(). Do not release a scene manually to prevent double releasing, which may cause scenes to be deleted.

Use obs_scene_from_source() to access a source from the list as an obs_scene_t object.

If you wish to keep a reference to a certain scene, use obs_source_get_ref() or obs_scene_get_ref() on that scene and release it with either obs_source_release() or obs_scene_release(). Use only one release function, as both releases the same object.

Parameters:
obs_source_t *obs_frontend_get_current_scene(void)
Returns:

A new reference to the currently active scene. Release with obs_source_release().

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. Release with obs_source_release().

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 scene collection 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:

  • collection – 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

Deprecated since version 30.0: Prefer obs_frontend_add_dock_by_id() or obs_frontend_add_custom_qdock() instead.

bool obs_frontend_add_dock_by_id(const char *id, const char *title, void *widget)

Adds a dock with the widget to the UI with a toggle in the Docks menu.

When the dock is closed, a custom QEvent of type QEvent::User + QEvent::Close is sent to the widget to enable it to react to the event (e.g., unload elements to save resources). A generic QShowEvent is already sent by default when the widget is being shown (e.g., dock opened).

Note: Use obs_frontend_remove_dock() to remove the dock

and the id from the UI.

Parameters:

  • id – Unique identifier of the dock

  • title – Window title of the dock

  • widget – QWidget to insert in the dock

Returns:

true if the dock was added, false if the id was already used

Added in version 30.0.

void obs_frontend_remove_dock(const char *id)

Removes the dock with this id from the UI.

Parameters:

  • id – Unique identifier of the dock to remove.

Added in version 30.0.

bool obs_frontend_add_custom_qdock(const char *id, void *dock)

Adds a custom dock to the UI with no toggle.

Note: Use obs_frontend_remove_dock() to remove the dock

reference and id from the UI.

Parameters:

  • id – Unique identifier of the dock

  • dock – QDockWidget to add

Returns:

true if the dock was added, false if the id was already used

Added in version 30.0.

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

bool obs_frontend_recording_split_file(void)

Asks OBS to split the current recording file.

Returns:

true if splitting was successfully requested (this does not mean that splitting has finished or guarantee that it split successfully), false if recording is inactive or paused or if file splitting is disabled.

bool obs_frontend_recording_add_chapter(const char *name)

Asks OBS to insert a chapter marker at the current output time into the recording.

Parameters:

  • name – The name for the chapter, may be NULL to use an automatically generated name (“Unnamed <Chapter number>” or localized equivalent).

Returns:

true if insertion was successful, false if recording is inactive, paused, or if chapter insertion is not supported by the current output.

Added in version 30.2.

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. Release with obs_output_release().

obs_output_t *obs_frontend_get_recording_output(void)
Returns:

A new reference to the current recording output. Release with obs_output_release().

obs_output_t *obs_frontend_get_replay_buffer_output(void)
Returns:

A new reference to the current replay buffer output. Release with obs_output_release().

config_t *obs_frontend_get_profile_config(void)
Returns:

The config_t* associated with the current profile

Deprecated since version 31.0.

config_t *obs_frontend_get_global_config(void)
Returns:

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

config_t *obs_frontend_get_app_config(void)
Returns:

The config_t* associated with system-wide settings (global.ini)

Added in version 31.0.

config_t *obs_frontend_get_user_config(void)
Returns:

The config_t* associated with user settings (user.ini)

Added in version 31.0.

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:

The current streaming service object. Does not increment the reference.

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. Release with obs_source_release().

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. Release with obs_output_release().

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

void *obs_frontend_open_sceneitem_edit_transform(obs_sceneitem_t *item)

Opens the edit transform window of the specified sceneitem.

Parameters:

  • item – The sceneitem to open the edit transform window of

Added in version 29.1.

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.

bool obs_frontend_is_theme_dark(void)
Returns:

Checks if the current theme is dark or light.

Added in version 29.0.0.

char *obs_frontend_get_last_recording(void)
Returns:

The file path of the last recording. Free with bfree()

Added in version 29.0.0.

char *obs_frontend_get_last_screenshot(void)
Returns:

The file path of the last screenshot taken. Free with bfree()

Added in version 29.0.0.

char *obs_frontend_get_last_replay(void)
Returns:

The file path of the last replay buffer saved. Free with bfree()

Added in version 29.0.0.

void obs_frontend_add_undo_redo_action(const char *name, const undo_redo_cb undo, const undo_redo_cb redo, const char *undo_data, const char *redo_data, bool repeatable)
Parameters:

  • name – The name of the undo redo action

  • undo – Callback to use for undo

  • redo – Callback to use for redo

  • undo_data – String with data for the undo callback

  • redo_data – String with data for the redo callback

  • repeatable – Allow multiple actions with the same name to be merged to 1 undo redo action. This uses the undo action from the first and the redo action from the last action.

Added in version 29.1.