OBS/obs-studio
OBS/obs-studio
1
0
Fork 0
mirror of https://github.com/obsproject/obs-studio.git synced 2024-07-04 10:33:30 +00:00
Code Issues Packages Projects Releases Wiki Activity
obs-studio/docs/sphinx/reference-frontend-api.rst
CodeYan01 f5fe9999b4 docs: Add info on obs_frontend_source_list
2023-12-02 18:01:55 -06:00

935 lines
27 KiB
ReStructuredText
Raw Blame History

OBS Studio Frontend API
=======================
The OBS Studio frontend API is the API specific to OBS Studio itself.
.. code:: cpp
#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.
.. versionadded:: 29.0.0
- **OBS_FRONTEND_EVENT_SCREENSHOT_TAKEN**
Triggered when a screenshot is taken.
.. versionadded:: 29.0.0
.. struct:: obs_frontend_source_list
- DARRAY(obs_source_t*) **sources**
Example usage:
.. code:: cpp
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);
.. type:: void (*obs_frontend_cb)(void *private_data)
Frontend tool menu callback
.. type:: void (*obs_frontend_event_cb)(enum obs_frontend_event event, void *private_data)
Frontend event callback
.. type:: void (*obs_frontend_save_cb)(obs_data_t *save_data, bool saving, void *private_data)
Frontend save/load callback
.. type:: bool (*obs_frontend_translate_ui_cb)(const char *text, const char **out)
Translation callback
.. type:: void (*undo_redo_cb)(const char *data)
Undo redo callback
Functions
---------
.. function:: void obs_frontend_source_list_free(struct obs_frontend_source_list *source_list)
Releases sources within a source list and frees the list.
:param source_list: Source list to free
---------------------------------------
.. function:: void *obs_frontend_get_main_window(void)
:return: The QMainWindow pointer to the OBS Studio window
---------------------------------------
.. function:: void *obs_frontend_get_main_window_handle(void)
:return: The native window handle of the OBS Studio window
---------------------------------------
.. function:: char **obs_frontend_get_scene_names(void)
:return: The scene name list, ending with NULL. The list is stored
within one contiguous segment of memory, so freeing the
returned pointer with :c:func:`bfree()` will free the entire
list. The order is same as the way the frontend displays it in
the Scenes dock.
---------------------------------------
.. function:: 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
:c:func:`obs_frontend_source_list_free`, which will automatically release all
scenes with :c:func:`obs_source_release`. Do not release a scene manually to
prevent double releasing, which may cause scenes to be deleted.
Use :c:func:`obs_scene_from_source` to access a source from the list as an
:c:type:`obs_scene_t` object.
If you wish to keep a reference to a certain scene, use
:c:func:`obs_source_get_ref` or :c:func:`obs_scene_get_ref` on that scene and
release it with either :c:func:`obs_source_release` or
:c:func:`obs_scene_release`. Use only one release function, as both releases
the same object.
:param sources: Pointer to a :c:type:`obs_frontend_source_list`
structure to receive the list of reference-incremented
scenes.
---------------------------------------
.. function:: obs_source_t *obs_frontend_get_current_scene(void)
:return: A new reference to the currently active scene. Release with
:c:func:`obs_source_release()`.
---------------------------------------
.. function:: void obs_frontend_set_current_scene(obs_source_t *scene)
:param scene: The scene to set as the current scene
---------------------------------------
.. function:: void obs_frontend_get_transitions(struct obs_frontend_source_list *sources)
:param sources: Pointer to a :c:type:`obs_frontend_source_list`
structure to receive the list of
reference-incremented transitions. Release with
:c:func:`obs_frontend_source_list_free`
---------------------------------------
.. function:: obs_source_t *obs_frontend_get_current_transition(void)
:return: A new reference to the currently active transition.
Release with :c:func:`obs_source_release()`.
---------------------------------------
.. function:: void obs_frontend_set_current_transition(obs_source_t *transition)
:param transition: The transition to set as the current transition
---------------------------------------
.. function:: int obs_frontend_get_transition_duration(void)
:return: The transition duration (in milliseconds) currently set in the UI
---------------------------------------
.. function:: void obs_frontend_set_transition_duration(int duration)
:param duration: Desired transition duration, in milliseconds
---------------------------------------
.. function:: void obs_frontend_release_tbar(void)
Emulate a mouse button release on the transition bar and determine transition status.
---------------------------------------
.. function:: void obs_frontend_set_tbar_position(int position)
Set the value of the transition bar.
:param position: The position to set the T-bar to, with a range of 0-1023
---------------------------------------
.. function:: int obs_frontend_get_tbar_position(void)
Get the value of the transition bar.
:return: The value of the position of the T-bar to, with a range of 0-1023
---------------------------------------
.. function:: char **obs_frontend_get_scene_collections(void)
:return: 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 :c:func:`bfree()` will free the
entire list.
---------------------------------------
.. function:: char *obs_frontend_get_current_scene_collection(void)
:return: A new pointer to the current scene collection name. Free
with :c:func:`bfree()`
---------------------------------------
.. function:: void obs_frontend_set_current_scene_collection(const char *collection)
:param collection: Name of the scene collection to activate
---------------------------------------
.. function:: bool obs_frontend_add_scene_collection(const char *name)
Add a new scene collection, then switch to it.
:param name: Name of the scene collection to add/create
---------------------------------------
.. function:: char **obs_frontend_get_profiles(void)
:return: The list of profile names, ending with NULL. The list is
stored within one contiguous segment of memory, so freeing
the returned pointer with :c:func:`bfree()` will free the
entire list.
---------------------------------------
.. function:: char *obs_frontend_get_current_profile(void)
:return: A new pointer to the current profile name. Free with
:c:func:`bfree()`
---------------------------------------
.. function:: char *obs_frontend_get_current_profile_path(void)
:return: A new pointer to the current profile's path on the
filesystem. Free with :c:func:`bfree()`
---------------------------------------
.. function:: void obs_frontend_set_current_profile(const char *profile)
:param profile: Name of the profile to activate
---------------------------------------
.. function:: bool obs_frontend_create_profile(const char *name)
:param name: Name of the new profile to create (must be unique)
---------------------------------------
.. function:: bool obs_frontend_duplicate_profile(const char *name)
:param name: Name of the duplicate profile to create (must be unique)
---------------------------------------
.. function:: void obs_frontend_delete_profile(const char *profile)
:param profile: Name of the profile to delete
---------------------------------------
.. function:: void *obs_frontend_add_tools_menu_qaction(const char *name)
Adds a QAction to the tools menu then returns it.
:param name: Name for the new menu item
:return: A pointer to the added QAction
---------------------------------------
.. function:: 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.
:param name: The name for the new menu item
:param callback: Callback to use when the menu item is clicked
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: void* obs_frontend_add_dock(void *dock)
Adds a QDockWidget to the UI's Docks menu.
:param dock: QDockWidget to add/create
:return: A pointer to the added QAction
.. deprecated:: 30.0
Prefer :c:func:`obs_frontend_add_dock_by_id()` or
:c:func:`obs_frontend_add_custom_qdock()` instead.
---------------------------------------
.. function:: 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.
Note: Use :c:func:`obs_frontend_remove_dock` to remove the dock
and the id from the UI.
:param id: Unique identifier of the dock
:param title: Window title of the dock
:param widget: QWidget to insert in the dock
:return: *true* if the dock was added, *false* if the id was already
used
---------------------------------------
.. function:: void obs_frontend_remove_dock(const char *id)
Removes the dock with this id from the UI.
:param id: Unique identifier of the dock to remove.
---------------------------------------
.. function:: bool obs_frontend_add_custom_qdock(const char *id, void *dock)
Adds a custom dock to the UI with no toggle.
Note: Use :c:func:`obs_frontend_remove_dock` to remove the dock
reference and id from the UI.
:param id: Unique identifier of the dock
:param dock: QDockWidget to add
:return: *true* if the dock was added, *false* if the id was already
used
---------------------------------------
.. function:: 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 :c:type:`obs_frontend_event` on what sort of events can be
triggered.
:param callback: Callback to use when a frontend event occurs
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: void obs_frontend_remove_event_callback(obs_frontend_event_cb callback, void *private_data)
Removes an event callback.
:param callback: Callback to remove
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: 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.
:param callback: Callback to use when saving/loading a scene
collection
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: void obs_frontend_remove_save_callback(obs_frontend_save_cb callback, void *private_data)
Removes a save/load callback.
:param callback: Callback to remove
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: 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.
:param callback: Callback to use when pre-loading
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: void obs_frontend_remove_preload_callback(obs_frontend_save_cb callback, void *private_data)
Removes a pre-load callback.
:param callback: Callback to remove
:param private_data: Private data associated with the callback
---------------------------------------
.. function:: 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.
:param translate: The translation callback to use
---------------------------------------
.. function:: void obs_frontend_pop_ui_translation(void)
Pops the current UI translation callback.
---------------------------------------
.. function:: void obs_frontend_streaming_start(void)
Starts streaming.
---------------------------------------
.. function:: void obs_frontend_streaming_stop(void)
Stops streaming.
---------------------------------------
.. function:: bool obs_frontend_streaming_active(void)
:return: *true* if streaming active, *false* otherwise
---------------------------------------
.. function:: void obs_frontend_recording_start(void)
Starts recording.
---------------------------------------
.. function:: void obs_frontend_recording_stop(void)
Stops recording.
---------------------------------------
.. function:: bool obs_frontend_recording_active(void)
:return: *true* if recording active, *false* otherwise
---------------------------------------
.. function:: void obs_frontend_recording_pause(bool pause)
:pause: *true* to pause recording, *false* to unpause
---------------------------------------
.. function:: bool obs_frontend_recording_paused(void)
:return: *true* if recording paused, *false* otherwise
---------------------------------------
.. function:: bool obs_frontend_recording_split_file(void)
Asks OBS to split the current recording file.
:return: *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.
---------------------------------------
.. function:: void obs_frontend_replay_buffer_start(void)
Starts the replay buffer.
---------------------------------------
.. function:: void obs_frontend_replay_buffer_stop(void)
Stops the replay buffer.
---------------------------------------
.. function:: void obs_frontend_replay_buffer_save(void)
Saves a replay if the replay buffer is active.
---------------------------------------
.. function:: bool obs_frontend_replay_buffer_active(void)
:return: *true* if replay buffer active, *false* otherwise
---------------------------------------
.. function:: void obs_frontend_open_projector(const char *type, int monitor, const char *geometry, const char *name)
:param type: "Preview", "Source", "Scene", "StudioProgram", or "Multiview" (case insensitive)
:param monitor: Monitor to open the projector on. If -1, this opens a window.
:param geometry: If *monitor* is -1, size and position of the projector window. Encoded in Base64 using Qt's geometry encoding.
:param name: If *type* is "Source" or "Scene", name of the source or scene to be displayed
---------------------------------------
.. function:: void obs_frontend_save(void)
Saves the current scene collection.
---------------------------------------
.. function:: obs_output_t *obs_frontend_get_streaming_output(void)
:return: A new reference to the current streaming output.
Release with :c:func:`obs_output_release()`.
---------------------------------------
.. function:: obs_output_t *obs_frontend_get_recording_output(void)
:return: A new reference to the current recording output.
Release with :c:func:`obs_output_release()`.
---------------------------------------
.. function:: obs_output_t *obs_frontend_get_replay_buffer_output(void)
:return: A new reference to the current replay buffer output.
Release with :c:func:`obs_output_release()`.
---------------------------------------
.. function:: config_t *obs_frontend_get_profile_config(void)
:return: The config_t* associated with the current profile
---------------------------------------
.. function:: config_t *obs_frontend_get_global_config(void)
:return: The config_t* associated with the global config (global.ini)
---------------------------------------
.. function:: void obs_frontend_set_streaming_service(obs_service_t *service)
Sets the current streaming service to stream with.
:param service: The streaming service to set
---------------------------------------
.. function:: obs_service_t *obs_frontend_get_streaming_service(void)
:return: The current streaming service object. Does not increment the
reference.
---------------------------------------
.. function:: void obs_frontend_save_streaming_service(void)
Saves the current streaming service data.
---------------------------------------
.. function:: bool obs_frontend_preview_program_mode_active(void)
:return: *true* if studio mode is active, *false* otherwise
---------------------------------------
.. function:: void obs_frontend_set_preview_program_mode(bool enable)
Activates/deactivates studio mode.
:param enable: *true* to activate studio mode, *false* to deactivate
studio mode
---------------------------------------
.. function:: void obs_frontend_preview_program_trigger_transition(void)
Triggers a preview-to-program transition if studio mode is active.
---------------------------------------
.. function:: obs_source_t *obs_frontend_get_current_preview_scene(void)
:return: A new reference to the current preview scene if studio mode
is active, or *NULL* if studio mode is not active. Release
with :c:func:`obs_source_release()`.
---------------------------------------
.. function:: 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.
:param scene: The scene to set as the current preview
---------------------------------------
.. function:: void obs_frontend_set_preview_enabled(bool enable)
Sets the enable state of the preview display. Only relevant with
studio mode disabled.
:param enable: *true* to enable preview, *false* to disable preview
---------------------------------------
.. function:: bool obs_frontend_preview_enabled(void)
:return: *true* if the preview display is enabled, *false* otherwise
---------------------------------------
.. function:: void *obs_frontend_take_screenshot(void)
Takes a screenshot of the main OBS output.
---------------------------------------
.. function:: void *obs_frontend_take_source_screenshot(obs_source_t *source)
Takes a screenshot of the specified source.
:param source: The source to take screenshot of
---------------------------------------
.. function:: obs_output_t *obs_frontend_get_virtualcam_output(void)
:return: A new reference to the current virtual camera output.
Release with :c:func:`obs_output_release()`.
---------------------------------------
.. function:: void obs_frontend_start_virtualcam(void)
Starts the virtual camera.
---------------------------------------
.. function:: void obs_frontend_stop_virtualcam(void)
Stops the virtual camera.
---------------------------------------
.. function:: bool obs_frontend_virtualcam_active(void)
:return: *true* if virtual camera is active, *false* otherwise
---------------------------------------
.. function:: void obs_frontend_reset_video(void)
Reloads the UI canvas and resets libobs video with latest data from
the current profile.
---------------------------------------
.. function:: void *obs_frontend_open_source_properties(obs_source_t *source)
Opens the properties window of the specified source.
:param source: The source to open the properties window of
---------------------------------------
.. function:: void *obs_frontend_open_source_filters(obs_source_t *source)
Opens the filters window of the specified source.
:param source: The source to open the filters window of
---------------------------------------
.. function:: 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.
:param source: The source to open the interact window of
---------------------------------------
.. function:: void *obs_frontend_open_sceneitem_edit_transform(obs_sceneitem_t *item)
Opens the edit transform window of the specified sceneitem.
:param item: The sceneitem to open the edit transform window of
.. versionadded:: 29.1
---------------------------------------
.. function:: char *obs_frontend_get_current_record_output_path(void)
:return: A new pointer to the current record output path. Free
with :c:func:`bfree()`
---------------------------------------
.. function:: const char *obs_frontend_get_locale_string(const char *string)
:return: Gets the frontend translation of a given string.
---------------------------------------
.. function:: bool obs_frontend_is_theme_dark(void)
:return: Checks if the current theme is dark or light.
.. versionadded:: 29.0.0
---------------------------------------
.. function:: char *obs_frontend_get_last_recording(void)
:return: The file path of the last recording. Free with :c:func:`bfree()`
.. versionadded:: 29.0.0
---------------------------------------
.. function:: char *obs_frontend_get_last_screenshot(void)
:return: The file path of the last screenshot taken. Free with
:c:func:`bfree()`
.. versionadded:: 29.0.0
---------------------------------------
.. function:: char *obs_frontend_get_last_replay(void)
:return: The file path of the last replay buffer saved. Free with
:c:func:`bfree()`
.. versionadded:: 29.0.0
---------------------------------------
.. function:: 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)
:param name: The name of the undo redo action
:param undo: Callback to use for undo
:param redo: Callback to use for redo
:param undo_data: String with data for the undo callback
:param redo_data: String with data for the redo callback
:param 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.
.. versionadded:: 29.1
Reference in a new issue View git blame Copy permalink