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.

• OBS_FRONTEND_EVENT_THEME_CHANGED

  Triggered when the theme is changed.

  New in version 29.0.0.

• OBS_FRONTEND_EVENT_SCREENSHOT_TAKEN

  Triggered when a screenshot is taken.

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

• sources – Pointer to a obs_frontend_source_list structure to receive the list of reference-incremented scenes. Release with obs_frontend_source_list_free()

---

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

• sources – Pointer to a obs_frontend_source_list structure to receive the list of reference-incremented transitions. Release with obs_frontend_source_list_free()

---

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

---

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.

---

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

---

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

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

---

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.

New in version 29.0.0.

---

char *obs_frontend_get_last_recording(void)

Returns

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

New in version 29.0.0.

---

char *obs_frontend_get_last_screenshot(void)

Returns

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

New 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()

New in version 29.0.0.