Source API Reference (obs_source_t) =================================== Sources are used to render video and/or audio on stream. Things such as capturing displays/games/audio, playing a video, showing an image, or playing audio. Sources can also be used to implement audio and video filters as well as transitions. The `libobs/obs-source.h`_ file is the dedicated header for implementing sources. .. type:: obs_source_t A reference-counted video/audio input source. .. type:: obs_weak_source_t A weak reference to an video/audio input source. .. code:: cpp #include Source Definition Structure (obs_source_info) --------------------------------------------- .. struct:: obs_source_info Source definition structure. .. member:: const char *obs_source_info.id Unique string identifier for the source (required). .. member:: enum obs_source_type obs_source_info.type Type of source. - **OBS_SOURCE_TYPE_INPUT** - Video/Audio Input - **OBS_SOURCE_TYPE_FILTER** - Filter - **OBS_SOURCE_TYPE_TRANSITION** - Transition .. member:: uint32_t obs_source_info.output_flags Source output capability flags (required). (Author's note: This should be renamed to "capability_flags") A bitwise OR combination of one or more of the following values: - **OBS_SOURCE_VIDEO** - Source has video Unless SOURCE_ASYNC_VIDEO is specified, the source must include the :c:member:`obs_source_info.video_render` callback in the source definition structure. - **OBS_SOURCE_AUDIO** - Source has audio Use the :c:func:`obs_source_output_audio()` function to pass raw audio data, which will be automatically converted and uploaded. If used with OBS_SOURCE_ASYNC_VIDEO, audio will automatically be synced up to the video output based upon their mutual timestamps. - **OBS_SOURCE_ASYNC** - Video is asynchronous (use OBS_SOURCE_ASYNC_VIDEO instead to automatically combine this flag with the OBS_SOURCE_VIDEO flag). - **OBS_SOURCE_ASYNC_VIDEO** - Source passes raw video data via RAM Use the :c:func:`obs_source_output_video()` function to pass raw video data, which will be automatically drawn at a timing relative to the provided timestamp. If audio is also present on the source, the audio will automatically be synced to the video based upon their mutual timestamps. - **OBS_SOURCE_CUSTOM_DRAW** - Source uses custom graphics calls, rather than just rendering a single texture. This capability flag must be used if the source does not use :c:func:`obs_source_draw()` to render a single texture. This capability flag is an important hint to turn off a specific optimization that allows the first effect filter in the filter chain to render the source directly with that effect filter. The optimization does not work if there are custom graphics calls, and the source must be rendered to a texture first before being sent to the first filter in the filter chain. (Author's note: Ironically, not many sources render with that optimization. I should have made it so that the optimization isn't used by default, and a flag should have been used to turn on the optimization -- not turn it off). - **OBS_SOURCE_INTERACTION** - Source can be interacted with by the user. When this is used, the source will receive interaction events if these callbacks are provided: :c:member:`obs_source_info.mouse_click`, :c:member:`obs_source_info.mouse_move`, :c:member:`obs_source_info.mouse_wheel`, :c:member:`obs_source_info.focus`, and :c:member:`obs_source_info.key_click`. - **OBS_SOURCE_COMPOSITE** - Source composites child sources When used, specifies that the source composites one or more child sources. Scenes and transitions are examples of sources that contain and render child sources. Sources that render sub-sources must implement the audio_render callback in order to perform custom audio mixing of child sources. This capability flag is always set for transitions. - **OBS_SOURCE_DO_NOT_DUPLICATE** - Source should not be fully duplicated. When this is used, specifies that the source should not be fully duplicated, and should prefer to duplicate via holding references rather than full duplication. When functions such as :c:func:`obs_source_duplicate()` or :c:func:`obs_scene_duplicate()` are called, sources or child sources with this flag will never be fully duplicated, and will instead only be referenced. An example of the type of sources that should not be fully duplicated are video devices, browsers, and video/audio captures, as they will either not function correctly or will cause performance or resource issues when duplicated. - **OBS_SOURCE_DEPRECATED** - Source is deprecated and should not be used. - **OBS_SOURCE_DO_NOT_SELF_MONITOR** - Audio of this source should not allow monitoring if the current monitoring device is the same device being captured by the source. This flag is used as a hint to the back-end to prevent the source from creating an audio feedback loop. This is primarily only used with desktop audio capture sources. - **OBS_SOURCE_CAP_DISABLED** - This source type has been disabled and should not be shown as a type of source the user can add. - **OBS_SOURCE_CAP_OBSOLETE** - This source type is obsolete and should not be shown as a type of source the user can add. Identical to *OBS_SOURCE_CAP_DISABLED*. Meant to be used when a source has changed in some way (mostly defaults/properties), but you want to avoid breaking older configurations. Basically solves the problem of "I want to change the defaults of a source but I don't want to break people's configurations" - **OBS_SOURCE_CONTROLLABLE_MEDIA** - This source has media that can be controlled - **OBS_SOURCE_MONITOR_BY_DEFAULT** - Source should enable monitoring by default. Monitoring should be set by the frontend if this flag is set. - **OBS_SOURCE_CEA_708** - Source type provides cea708 data - **OBS_SOURCE_SRGB** - Source understands SRGB rendering - **OBS_SOURCE_CAP_DONT_SHOW_PROPERTIES** - Source type prefers not to have its properties shown on creation (prefers to rely on defaults first) .. member:: const char *(*obs_source_info.get_name)(void *type_data) Get the translated name of the source type. :param type_data: The type_data variable of this structure :return: The translated name of the source type .. member:: void *(*obs_source_info.create)(obs_data_t *settings, obs_source_t *source) Creates the implementation data for the source. :param settings: Settings to initialize the source with :param source: Source that this data is associated with :return: The implementation data associated with this source .. member:: void (*obs_source_info.destroy)(void *data) Destroys the implementation data for the source. Async sources must not call obs_source_output_video after returning from destroy. .. member:: uint32_t (*obs_source_info.get_width)(void *data) uint32_t (*obs_source_info.get_height)(void *data) Returns the width/height of the source. These callbacks are required if this is a video source and is synchronous. (Author's note: These should really be consolidated in to one function, not two) :return: The width/height of the video .. member:: void (*obs_source_info.get_defaults)(obs_data_t *settings) void (*obs_source_info.get_defaults2)(void *type_data, obs_data_t *settings) Sets the default settings for this source. :param settings: Default settings. Call obs_data_set_default* functions on this object to set default setting values .. member:: obs_properties_t *(*obs_source_info.get_properties)(void *data) obs_properties_t *(*obs_source_info.get_properties2)(void *data, void *type_data) Gets the property information of this source. (Optional) :return: The properties of the source .. member:: void (*obs_source_info.update)(void *data, obs_data_t *settings) Updates the settings for this source. (Optional) :param settings: New settings for this source .. member:: void (*obs_source_info.activate)(void *data) Called when the source has been activated in the main view (visible on stream/recording). (Optional) .. member:: void (*obs_source_info.deactivate)(void *data) Called when the source has been deactivated from the main view (no longer visible on stream/recording). (Optional) .. member:: void (*obs_source_info.show)(void *data) Called when the source is visible on any display and/or on the main view. (Optional) .. member:: void (*obs_source_info.hide)(void *data) Called when the source is no longer visible on any display and/or on the main view. (Optional) .. member:: void (*obs_source_info.video_tick)(void *data, float seconds) Called each video frame with the time elapsed. (Optional) :param seconds: Seconds elapsed since the last frame .. member:: void (*obs_source_info.video_render)(void *data, gs_effect_t *effect) Called when rendering the source with the graphics subsystem. If this is an input/transition source, this is called to draw the source texture with the graphics subsystem. If this is a filter source, it wraps source draw calls (for example applying a custom effect with custom parameters to a source). In this case, it's highly recommended to use the :c:func:`obs_source_process_filter_begin()` and :c:func:`obs_source_process_filter_end()` functions to automatically handle effect-based filter processing. However, you can implement custom draw handling as desired as well. If the source output capability flags do not include OBS_SOURCE_CUSTOM_DRAW, the source must use :c:func:`obs_source_draw()` to render the source's texture. :param effect: This parameter is no longer used. Instead, call :c:func:`obs_source_draw()` .. member:: struct obs_source_frame *(*obs_source_info.filter_video)(void *data, struct obs_source_frame *frame) Called to filter raw async video data. This function is only used with asynchronous video filters. :param frame: Video frame to filter :return: New video frame data. This can defer video data to be drawn later if time is needed for processing .. member:: struct obs_audio_data *(*obs_source_info.filter_audio)(void *data, struct obs_audio_data *audio) Called to filter raw audio data. This function is only used with audio filters. :param audio: Audio data to filter :return: Modified or new audio data. You can directly modify the data passed and return it, or you can defer audio data for later if time is needed for processing. If you are returning new data, that data must exist until the next call to the :c:member:`obs_source_info.filter_audio` callback or until the filter is removed/destroyed .. member:: void (*obs_source_info.enum_active_sources)(void *data, obs_source_enum_proc_t enum_callback, void *param) Called to enumerate all active sources being used within this source. If the source has children that render audio/video it must implement this callback. Only used with sources that have the OBS_SOURCE_COMPOSITE output capability flag. :param enum_callback: Enumeration callback :param param: User data to pass to callback .. member:: void (*obs_source_info.save)(void *data, obs_data_t *settings) Called when saving custom data for a source. This is a separate function because sometimes a source needs to know when it is being saved so it doesn't always have to update the current settings until a certain point. (Optional) :param settings: Settings object to save data to .. member:: void (*obs_source_info.load)(void *data, obs_data_t *settings) Called when loading custom data from saved source data. This is called after all the loading sources have actually been created, allowing the ability to reference other sources if desired. (Optional) :param settings: Settings object to load data from .. member:: void (*obs_source_info.mouse_click)(void *data, const struct obs_mouse_event *event, int32_t type, bool mouse_up, uint32_t click_count) Called when interacting with a source and a mouse-down or mouse-up occurs. Only used with sources that have the OBS_SOURCE_INTERACTION output capability flag. (Optional) :param event: Mouse event properties :param type: Mouse button pushed :param mouse_up: Mouse event type (true if mouse-up) :param click_count: Mouse click count (1 for single click, etc.) .. member:: void (*obs_source_info.mouse_move)(void *data, const struct obs_mouse_event *event, bool mouse_leave) Called when interacting with a source and a mouse-move occurs. Only used with sources that have the OBS_SOURCE_INTERACTION output capability flag. (Optional) :param event: Mouse event properties :param mouse_leave: Mouse leave state (true if mouse left source) .. member:: void (*obs_source_info.mouse_wheel)(void *data, const struct obs_mouse_event *event, int x_delta, int y_delta) Called when interacting with a source and a mouse-wheel occurs. Only used with sources that have the OBS_SOURCE_INTERACTION output capability flag. (Optional) :param event: Mouse event properties :param x_delta: Movement delta in the horizontal direction :param y_delta: Movement delta in the vertical direction .. member:: void (*obs_source_info.focus)(void *data, bool focus) Called when interacting with a source and gain focus/lost focus event occurs. Only used with sources that have the OBS_SOURCE_INTERACTION output capability flag. (Optional) :param focus: Focus state (true if focus gained) .. member:: void (*obs_source_info.key_click)(void *data, const struct obs_key_event *event, bool key_up) Called when interacting with a source and a key-up or key-down occurs. Only used with sources that have the OBS_SOURCE_INTERACTION output capability flag. (Optional) :param event: Key event properties :param focus: Key event type (true if mouse-up) .. member:: void (*obs_source_info.filter_remove)(void *data, obs_source_t *source) Called when the filter is removed from a source. (Optional) :param data: Filter data :param source: Source that the filter being removed from .. member:: void *obs_source_info.type_data void (*obs_source_info.free_type_data)(void *type_data) Private data associated with this entry. Note that this is not the same as the implementation data; this is used to differentiate between two different types if the same callbacks are used for more than one different type. .. member:: bool (*obs_source_info.audio_render)(void *data, uint64_t *ts_out, struct obs_source_audio_mix *audio_output, uint32_t mixers, size_t channels, size_t sample_rate) Called to render audio of composite sources. Only used with sources that have the OBS_SOURCE_COMPOSITE output capability flag. .. member:: void (*obs_source_info.enum_all_sources)(void *data, obs_source_enum_proc_t enum_callback, void *param) Called to enumerate all active and inactive sources being used within this source. If this callback isn't implemented, enum_active_sources will be called instead. Only used with sources that have the OBS_SOURCE_COMPOSITE output capability flag. This is typically used if a source can have inactive child sources. :param enum_callback: Enumeration callback :param param: User data to pass to callback .. member:: void (*obs_source_info.transition_start)(void *data) void (*obs_source_info.transition_stop)(void *data) Called on transition sources when the transition starts/stops. (Optional) .. member:: enum obs_icon_type obs_source_info.icon_type Icon used for the source. - **OBS_ICON_TYPE_UNKNOWN** - Unknown - **OBS_ICON_TYPE_IMAGE** - Image - **OBS_ICON_TYPE_COLOR** - Color - **OBS_ICON_TYPE_SLIDESHOW** - Slideshow - **OBS_ICON_TYPE_AUDIO_INPUT** - Audio Input - **OBS_ICON_TYPE_AUDIO_OUTPUT** - Audio Output - **OBS_ICON_TYPE_DESKTOP_CAPTURE** - Desktop Capture - **OBS_ICON_TYPE_WINDOW_CAPTURE** - Window Capture - **OBS_ICON_TYPE_GAME_CAPTURE** - Game Capture - **OBS_ICON_TYPE_CAMERA** - Camera - **OBS_ICON_TYPE_TEXT** - Text - **OBS_ICON_TYPE_MEDIA** - Media - **OBS_ICON_TYPE_BROWSER** - Browser - **OBS_ICON_TYPE_CUSTOM** - Custom (not implemented yet) .. member:: void (*obs_source_info.media_play_pause)(void *data, bool pause) Called to pause or play media. .. member:: void (*obs_source_info.media_restart)(void *data) Called to restart the media. .. member:: void (*obs_source_info.media_stop)(void *data) Called to stop the media. .. member:: void (*obs_source_info.media_next)(void *data) Called to go to the next media. .. member:: void (*obs_source_info.media_previous)(void *data) Called to go to the previous media. .. member:: int64_t (*obs_source_info.media_get_duration)(void *data) Called to get the media duration. .. member:: int64_t (*obs_source_info.media_get_time)(void *data) Called to get the current time of the media. .. member:: void (*obs_source_info.media_set_time)(void *data, int64_t miliseconds) Called to set the media time. .. member:: enum obs_media_state (*obs_source_info.media_get_state)(void *data) Called to get the state of the media. - **OBS_MEDIA_STATE_NONE** - None - **OBS_MEDIA_STATE_PLAYING** - Playing - **OBS_MEDIA_STATE_OPENING** - Opening - **OBS_MEDIA_STATE_BUFFERING** - Buffering - **OBS_MEDIA_STATE_PAUSED** - Paused - **OBS_MEDIA_STATE_STOPPED** - Stopped - **OBS_MEDIA_STATE_ENDED** - Ended - **OBS_MEDIA_STATE_ERROR** - Error .. member:: enum gs_color_space (*obs_source_info.video_get_color_space)(void *data, size_t count, const enum gs_color_space *preferred_spaces) Returns the color space of the source. Assume GS_CS_SRGB if not implemented. There's an optimization an SDR source can do when rendering to HDR. Check if the active space is GS_CS_709_EXTENDED, and return GS_CS_709_EXTENDED instead of GS_CS_SRGB to avoid an redundant conversion. This optimization can only be done if the pixel shader outputs linear 709, which is why it's not performed by default. :return: The color space of the video .. _source_signal_handler_reference: Source Signals -------------- **destroy** (ptr *source*) This signal is called when the source is about to be destroyed. Do not increment any references when using this signal. **remove** (ptr source) Called when the :c:func:`obs_source_remove()` function is called on the source. **save** (ptr source) Called when the source is being saved. **load** (ptr source) Called when the source is being loaded. **activate** (ptr source) Called when the source has been activated in the main view (visible on stream/recording). **deactivate** (ptr source) Called when the source has been deactivated from the main view (no longer visible on stream/recording). **show** (ptr source) Called when the source is visible on any display and/or on the main view. **hide** (ptr source) Called when the source is no longer visible on any display and/or on the main view. **mute** (ptr source, bool muted) Called when the source is muted/unmuted. **push_to_mute_changed** (ptr source, bool enabled) Called when push-to-mute has been enabled/disabled. **push_to_mute_delay** (ptr source, int delay) Called when the push-to-mute delay value has changed. **push_to_talk_changed** (ptr source, bool enabled) Called when push-to-talk has been enabled/disabled. **push_to_talk_delay** (ptr source, int delay) Called when the push-to-talk delay value has changed. **enable** (ptr source, bool enabled) Called when the source has been disabled/enabled. **rename** (ptr source, string new_name, string prev_name) Called when the source has been renamed. **volume** (ptr source, in out float volume) Called when the volume of the source has changed. **update_properties** (ptr source) Called when the properties of the source have been updated. **update_flags** (ptr source, int flags) Called when the flags of the source have been changed. **audio_sync** (ptr source, int out int offset) Called when the audio sync offset has changed. **audio_balance** (ptr source, in out float balance) Called when the audio balance has changed. **audio_mixers** (ptr source, in out int mixers) Called when the audio mixers have changed. **filter_add** (ptr source, ptr filter) Called when a filter has been added to the source. **filter_remove** (ptr source, ptr filter) Called when a filter has been removed from the source. **reorder_filters** (ptr source) Called when filters have been reordered. **transition_start** (ptr source) Called when a transition is starting. **transition_video_stop** (ptr source) Called when a transition's video transitioning has stopped. **transition_stop** (ptr source) Called when a transition has stopped. **media_started** Called when media has started. **media_ended** Called when media has ended. **media_pause** Called when media has been paused. **media_play** Called when media starts playing. **media_restart** Called when the playing of media has been restarted. **media_stopped** Called when the playing of media has been stopped. **media_next** Called when the media source switches to the next media. **media_previous** Called when the media source switches to the previous media. General Source Functions ------------------------ .. function:: void obs_register_source(struct obs_source_info *info) Registers a source type. Typically used in :c:func:`obs_module_load()` or in the program's initialization phase. --------------------- .. function:: const char *obs_source_get_display_name(const char *id) Calls the :c:member:`obs_source_info.get_name` callback to get the translated display name of a source type. :param id: The source type string identifier :return: The translated display name of a source type --------------------- .. function:: obs_source_t *obs_source_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data) Creates a source of the specified type with the specified settings. The "source" context is used for anything related to presenting or modifying video/audio. Use obs_source_release to release it. :param id: The source type string identifier :param name: The desired name of the source. If this is not unique, it will be made to be unique :param settings: The settings for the source, or *NULL* if none :param hotkey_data: Saved hotkey data for the source, or *NULL* if none :return: A reference to the newly created source, or *NULL* if failed --------------------- .. function:: obs_source_t *obs_source_create_private(const char *id, const char *name, obs_data_t *settings) Creates a 'private' source which is not enumerated by :c:func:`obs_enum_sources()`, and is not saved by :c:func:`obs_save_sources()`. Author's Note: The existence of this function is a result of design flaw: the front-end should control saving/loading of sources, and functions like :c:func:`obs_enum_sources()` and :c:func:`obs_save_sources()` should not exist in the back-end. :param id: The source type string identifier :param name: The desired name of the source. For private sources, this does not have to be unique, and can additionally be *NULL* if desired :param settings: The settings for the source, or *NULL* if none :return: A reference to the newly created source, or *NULL* if failed --------------------- .. function:: obs_source_t *obs_source_duplicate(obs_source_t *source, const char *desired_name, bool create_private) Duplicates a source. If the source has the OBS_SOURCE_DO_NOT_DUPLICATE output flag set, this only returns a new reference to the same source. :param source: The source to duplicate :param desired_name: The desired name of the new source. If this is not a private source and the name is not unique, it will be made to be unique :param create_private: If *true*, the new source will be a private source if fully duplicated :return: A new source reference --------------------- .. function:: void obs_source_addref(obs_source_t *source) Adds a reference to a source. .. deprecated:: 27.2.0 Use :c:func:`obs_source_get_ref()` instead. --------------------- .. function:: obs_source_t *obs_source_get_ref(obs_source_t *source) Returns an incremented reference if still valid, otherwise returns *NULL*. --------------------- .. function:: void obs_source_release(obs_source_t *source) Releases a reference to a source. When the last reference is released, the source is destroyed. --------------------- .. function:: obs_weak_source_t *obs_source_get_weak_source(obs_source_t *source) obs_source_t *obs_weak_source_get_source(obs_weak_source_t *weak) These functions are used to get a weak reference from a strong source reference, or a strong source reference from a weak reference. If the source is destroyed, *obs_weak_source_get_source* will return *NULL*. --------------------- .. function:: void obs_weak_source_addref(obs_weak_source_t *weak) void obs_weak_source_release(obs_weak_source_t *weak) Adds/releases a weak reference to a source. --------------------- .. function:: void obs_source_remove(obs_source_t *source) Notifies all reference holders of the source (via :c:func:`obs_source_removed()`) that the source should be released. --------------------- .. function:: bool obs_source_removed(const obs_source_t *source) :return: *true* if the source should be released --------------------- .. function:: bool obs_source_is_hidden(obs_source_t *source) void obs_source_set_hidden(obs_source_t *source, bool hidden) Gets/sets the hidden property that determines whether it should be hidden from the user. Used when the source is still alive but should not be referenced. --------------------- .. function:: uint32_t obs_source_get_output_flags(const obs_source_t *source) uint32_t obs_get_source_output_flags(const char *id) :return: Capability flags of a source Author's Note: "Output flags" is poor wording in retrospect; this should have been named "Capability flags", and the OBS_SOURCE_* macros should really be OBS_SOURCE_CAP_* macros instead. See :c:member:`obs_source_info.output_flags` for more information. --------------------- .. function:: obs_data_t *obs_get_source_defaults(const char *id) Calls :c:member:`obs_source_info.get_defaults` to get the defaults settings of the source type. :return: The default settings for a source type --------------------- .. function:: obs_properties_t *obs_source_properties(const obs_source_t *source) obs_properties_t *obs_get_source_properties(const char *id) Use these functions to get the properties of a source or source type. Properties are optionally used (if desired) to automatically generate user interface widgets to allow users to update settings. :return: The properties list for a specific existing source. Free with :c:func:`obs_properties_destroy()` --------------------- .. function:: bool obs_source_configurable(const obs_source_t *source) bool obs_is_source_configurable(const char *id) :return: *true* if the the source has custom properties, *false* otherwise --------------------- .. function:: void obs_source_update(obs_source_t *source, obs_data_t *settings) Updates the settings for a source and calls the :c:member:`obs_source_info.update` callback of the source. If the source is a video source, the :c:member:`obs_source_info.update` will be not be called immediately; instead, it will be deferred to the video thread to prevent threading issues. --------------------- .. function:: void obs_source_reset_settings(obs_source_t *source, obs_data_t *settings) Same as :c:func:`obs_source_update`, but clears existing settings first. --------------------- .. function:: void obs_source_video_render(obs_source_t *source) Renders a video source. This will call the :c:member:`obs_source_info.video_render` callback of the source. --------------------- .. function:: uint32_t obs_source_get_width(obs_source_t *source) uint32_t obs_source_get_height(obs_source_t *source) Calls the :c:member:`obs_source_info.get_width` or :c:member:`obs_source_info.get_height` of the source to get its width and/or height. Author's Note: These functions should be consolidated in to a single function/callback rather than having a function for both width and height. :return: The width or height of the source --------------------- .. function:: enum gs_color_space obs_source_get_color_space(obs_source_t *source, size_t count, const enum gs_color_space *preferred_spaces) Calls the :c:member:`obs_source_info.video_get_color_space` of the source to get its color space. Assumes GS_CS_SRGB if not implemented. Disabled filters are skipped, and async video sources can figure out the color space for themselves. :return: The color space of the source --------------------- .. function:: bool obs_source_get_texcoords_centered(obs_source_t *source) Hints whether or not the source will blend texels. :return: Whether or not the source will blend texels --------------------- .. function:: obs_data_t *obs_source_get_settings(const obs_source_t *source) :return: The settings string for a source. The reference counter of the returned settings data is incremented, so :c:func:`obs_data_release()` must be called when the settings are no longer used --------------------- .. function:: const char *obs_source_get_name(const obs_source_t *source) :return: The name of the source --------------------- .. function:: void obs_source_set_name(obs_source_t *source, const char *name) Sets the name of a source. If the source is not private and the name is not unique, it will automatically be given a unique name. --------------------- .. function:: enum obs_source_type obs_source_get_type(const obs_source_t *source) :return: | OBS_SOURCE_TYPE_INPUT for inputs | OBS_SOURCE_TYPE_FILTER for filters | OBS_SOURCE_TYPE_TRANSITION for transitions | OBS_SOURCE_TYPE_SCENE for scenes --------------------- .. function:: const char *obs_source_get_id(const obs_source_t *source) :return: The source's type identifier string --------------------- .. function:: signal_handler_t *obs_source_get_signal_handler(const obs_source_t *source) :return: The source's signal handler See the :ref:`source_signal_handler_reference` for more information on signals that are available for sources. --------------------- .. function:: proc_handler_t *obs_source_get_proc_handler(const obs_source_t *source) :return: The procedure handler for a source --------------------- .. function:: void obs_source_set_volume(obs_source_t *source, float volume) float obs_source_get_volume(const obs_source_t *source) Sets/gets the user volume for a source that has audio output. --------------------- .. function:: bool obs_source_muted(const obs_source_t *source) void obs_source_set_muted(obs_source_t *source, bool muted) Sets/gets whether the source's audio is muted. --------------------- .. function:: enum speaker_layout obs_source_get_speaker_layout(obs_source_t *source) Gets the current speaker layout. --------------------- .. function:: void obs_source_set_balance_value(obs_source_t *source, float balance) float obs_source_get_balance_value(const obs_source_t *source) Sets/gets the audio balance value. --------------------- .. function:: void obs_source_set_sync_offset(obs_source_t *source, int64_t offset) int64_t obs_source_get_sync_offset(const obs_source_t *source) Sets/gets the audio sync offset (in nanoseconds) for a source. --------------------- .. function:: void obs_source_set_audio_mixers(obs_source_t *source, uint32_t mixers) uint32_t obs_source_get_audio_mixers(const obs_source_t *source) Sets/gets the audio mixer channels that a source outputs to, depending on what bits are set. Audio mixers allow filtering specific using multiple audio encoders to mix different sources together depending on what mixer channel they're set to. For example, to output to mixer 1 and 3, you would perform a bitwise OR on bits 0 and 2: (1<<0) | (1<<2), or 0x5. --------------------- .. function:: void obs_source_set_monitoring_type(obs_source_t *source, enum obs_monitoring_type type) enum obs_monitoring_type obs_source_get_monitoring_type(obs_source_t *source) Sets/gets the desktop audio monitoring type. :param order: | OBS_MONITORING_TYPE_NONE - Do not monitor | OBS_MONITORING_TYPE_MONITOR_ONLY - Send to monitor device, no outputs | OBS_MONITORING_TYPE_MONITOR_AND_OUTPUT - Send to monitor device and outputs --------------------- .. function:: void obs_source_enum_active_sources(obs_source_t *source, obs_source_enum_proc_t enum_callback, void *param) void obs_source_enum_active_tree(obs_source_t *source, obs_source_enum_proc_t enum_callback, void *param) Enumerates active child sources or source tree used by this source. Relevant data types used with this function: .. code:: cpp typedef void (*obs_source_enum_proc_t)(obs_source_t *parent, obs_source_t *child, void *param); --------------------- .. function:: bool obs_source_push_to_mute_enabled(const obs_source_t *source) void obs_source_enable_push_to_mute(obs_source_t *source, bool enabled) Sets/gets whether push-to-mute is enabled. --------------------- .. function:: uint64_t obs_source_get_push_to_mute_delay(const obs_source_t *source) void obs_source_set_push_to_mute_delay(obs_source_t *source, uint64_t delay) Sets/gets the push-to-mute delay. --------------------- .. function:: bool obs_source_push_to_talk_enabled(const obs_source_t *source) void obs_source_enable_push_to_talk(obs_source_t *source, bool enabled) Sets/gets whether push-to-talk is enabled. --------------------- .. function:: uint64_t obs_source_get_push_to_talk_delay(const obs_source_t *source) void obs_source_set_push_to_talk_delay(obs_source_t *source, uint64_t delay) Sets/gets the push-to-talk delay. --------------------- .. function:: bool obs_source_active(const obs_source_t *source) :return: *true* if active, *false* if not. A source is only considered active if it's being shown on the final mix --------------------- .. function:: bool obs_source_showing(const obs_source_t *source) :return: *true* if showing, *false* if not. A source is considered showing if it's being displayed anywhere at all, whether on a display context or on the final output --------------------- .. function:: void obs_source_inc_showing(obs_source_t *source) void obs_source_dec_showing(obs_source_t *source) Increments/decrements a source's "showing" state. Typically used when drawing a source on a display manually. --------------------- .. function:: void obs_source_set_flags(obs_source_t *source, uint32_t flags) uint32_t obs_source_get_flags(const obs_source_t *source) :param flags: OBS_SOURCE_FLAG_FORCE_MONO Forces audio to mono --------------------- .. function:: void obs_source_enum_filters(obs_source_t *source, obs_source_enum_proc_t callback, void *param) Enumerates active filters on a source. Relevant data types used with this function: .. code:: cpp typedef void (*obs_source_enum_proc_t)(obs_source_t *parent, obs_source_t *child, void *param); --------------------- .. function:: obs_source_t *obs_source_get_filter_by_name(obs_source_t *source, const char *name) :return: The desired filter, or *NULL* if not found. The reference of the filter is incremented --------------------- .. function:: void obs_source_copy_filters(obs_source_t *dst, obs_source_t *src) Copies filters from the source to the destination. If filters by the same name already exist in the destination source, the newer filters will be given unique names. --------------------- .. function:: size_t obs_source_filter_count(const obs_source_t *source) Returns the number of filters the source has. --------------------- .. function:: obs_data_array_t *obs_source_backup_filters(obs_source_t *source) void obs_source_restore_filters(obs_source_t *source, obs_data_array_t *array) Backs up and restores the current filter list and order. --------------------- .. function:: bool obs_source_enabled(const obs_source_t *source) void obs_source_set_enabled(obs_source_t *source, bool enabled) Enables/disables a source, or returns the enabled state. --------------------- .. function:: void obs_source_add_audio_capture_callback(obs_source_t *source, obs_source_audio_capture_t callback, void *param) void obs_source_remove_audio_capture_callback(obs_source_t *source, obs_source_audio_capture_t callback, void *param) Adds/removes an audio capture callback for a source. This allows the ability to get the raw audio data of a source as it comes in. Relevant data types used with this function: .. code:: cpp typedef void (*obs_source_audio_capture_t)(void *param, obs_source_t *source, const struct audio_data *audio_data, bool muted); --------------------- .. function:: void obs_source_set_deinterlace_mode(obs_source_t *source, enum obs_deinterlace_mode mode) enum obs_deinterlace_mode obs_source_get_deinterlace_mode(const obs_source_t *source) Sets/gets the deinterlace mode. :param mode: | OBS_DEINTERLACE_MODE_DISABLE - Disables deinterlacing | OBS_DEINTERLACE_MODE_DISCARD - Discard | OBS_DEINTERLACE_MODE_RETRO - Retro | OBS_DEINTERLACE_MODE_BLEND - Blend | OBS_DEINTERLACE_MODE_BLEND_2X - Blend 2x | OBS_DEINTERLACE_MODE_LINEAR - Linear | OBS_DEINTERLACE_MODE_LINEAR_2X - Linear 2x | OBS_DEINTERLACE_MODE_YADIF - Yadif | OBS_DEINTERLACE_MODE_YADIF_2X - Yadif 2x --------------------- .. function:: void obs_source_set_deinterlace_field_order(obs_source_t *source, enum obs_deinterlace_field_order order) enum obs_deinterlace_field_order obs_source_get_deinterlace_field_order(const obs_source_t *source) Sets/gets the deinterlace field order. :param order: | OBS_DEINTERLACE_FIELD_ORDER_TOP - Start from top | OBS_DEINTERLACE_FIELD_ORDER_BOTTOM - Start from bottom --------------------- .. function:: obs_data_t *obs_source_get_private_settings(obs_source_t *item) Gets private front-end settings data. This data is saved/loaded automatically. Returns an incremented reference. --------------------- .. function:: void obs_source_send_mouse_click(obs_source_t *source, const struct obs_mouse_event *event, int32_t type, bool mouse_up, uint32_t click_count) Used for interacting with sources: sends a mouse down/up event to a source. --------------------- .. function:: void obs_source_send_mouse_move(obs_source_t *source, const struct obs_mouse_event *event, bool mouse_leave) Used for interacting with sources: sends a mouse move event to a source. --------------------- .. function:: void obs_source_send_mouse_wheel(obs_source_t *source, const struct obs_mouse_event *event, int x_delta, int y_delta) Used for interacting with sources: sends a mouse wheel event to a source. --------------------- .. function:: void obs_source_send_focus(obs_source_t *source, bool focus) Used for interacting with sources: sends a got-focus or lost-focus event to a source. --------------------- .. function:: void obs_source_send_key_click(obs_source_t *source, const struct obs_key_event *event, bool key_up) Used for interacting with sources: sends a key up/down event to a source. --------------------- Functions used by sources ------------------------- .. function:: void obs_source_draw_set_color_matrix(const struct matrix4 *color_matrix, const struct vec3 *color_range_min, const struct vec3 *color_range_max) Helper function to set the color matrix information when drawing the source. :param color_matrix: The color matrix. Assigns to the 'color_matrix' effect variable. :param color_range_min: The minimum color range. Assigns to the 'color_range_min' effect variable. If NULL, {0.0f, 0.0f, 0.0f} is used. :param color_range_max: The maximum color range. Assigns to the 'color_range_max' effect variable. If NULL, {1.0f, 1.0f, 1.0f} is used. --------------------- .. function:: void obs_source_draw(gs_texture_t *image, int x, int y, uint32_t cx, uint32_t cy, bool flip) Helper function to draw sprites for a source (synchronous video). :param image: The sprite texture to draw. Assigns to the 'image' variable of the current effect. :param x: X position of the sprite. :param y: Y position of the sprite. :param cx: Width of the sprite. If 0, uses the texture width. :param cy: Height of the sprite. If 0, uses the texture height. :param flip: Specifies whether to flip the image vertically. --------------------- .. function:: void obs_source_output_video(obs_source_t *source, const struct obs_source_frame *frame) Outputs asynchronous video data. Set to NULL to deactivate the texture. Relevant data types used with this function: .. code:: cpp enum video_format { VIDEO_FORMAT_NONE, /* planar 4:2:0 formats */ VIDEO_FORMAT_I420, /* three-plane */ VIDEO_FORMAT_NV12, /* two-plane, luma and packed chroma */ /* packed 4:2:2 formats */ VIDEO_FORMAT_YVYU, VIDEO_FORMAT_YUY2, /* YUYV */ VIDEO_FORMAT_UYVY, /* packed uncompressed formats */ VIDEO_FORMAT_RGBA, VIDEO_FORMAT_BGRA, VIDEO_FORMAT_BGRX, VIDEO_FORMAT_Y800, /* grayscale */ /* planar 4:4:4 */ VIDEO_FORMAT_I444, /* more packed uncompressed formats */ VIDEO_FORMAT_BGR3, /* planar 4:2:2 */ VIDEO_FORMAT_I422, /* planar 4:2:0 with alpha */ VIDEO_FORMAT_I40A, /* planar 4:2:2 with alpha */ VIDEO_FORMAT_I42A, /* planar 4:4:4 with alpha */ VIDEO_FORMAT_YUVA, /* packed 4:4:4 with alpha */ VIDEO_FORMAT_AYUV, /* planar 4:2:0 format, 10 bpp */ VIDEO_FORMAT_I010, /* three-plane */ VIDEO_FORMAT_P010, /* two-plane, luma and packed chroma */ }; struct obs_source_frame { uint8_t *data[MAX_AV_PLANES]; uint32_t linesize[MAX_AV_PLANES]; uint32_t width; uint32_t height; uint64_t timestamp; enum video_format format; float color_matrix[16]; bool full_range; uint16_t max_luminance; float color_range_min[3]; float color_range_max[3]; bool flip; uint8_t flags; uint8_t trc; /* enum video_trc */ }; --------------------- .. function:: void obs_source_set_async_rotation(obs_source_t *source, long rotation) Allows the ability to set rotation (0, 90, 180, -90, 270) for an async video source. The rotation will be automatically applied to the source. --------------------- .. function:: void obs_source_preload_video(obs_source_t *source, const struct obs_source_frame *frame) Preloads a video frame to ensure a frame is ready for playback as soon as video playback starts. --------------------- .. function:: void obs_source_show_preloaded_video(obs_source_t *source) Shows any preloaded video frame. --------------------- .. function:: void obs_source_output_audio(obs_source_t *source, const struct obs_source_audio *audio) Outputs audio data. --------------------- .. function:: void obs_source_update_properties(obs_source_t *source) Signal an update to any currently used properties. --------------------- .. function:: bool obs_source_add_active_child(obs_source_t *parent, obs_source_t *child) Adds an active child source. Must be called by parent sources on child sources when the child is added and active. This ensures that the source is properly activated if the parent is active. :return: *true* if source can be added, *false* if it causes recursion --------------------- .. function:: void obs_source_remove_active_child(obs_source_t *parent, obs_source_t *child) Removes an active child source. Must be called by parent sources on child sources when the child is removed or inactive. This ensures that the source is properly deactivated if the parent is no longer active. --------------------- Filters ------- .. function:: obs_source_t *obs_filter_get_parent(const obs_source_t *filter) If the source is a filter, returns the parent source of the filter. The parent source is the source being filtered. Only guaranteed to be valid inside of the video_render, filter_audio, filter_video, and filter_remove callbacks. --------------------- .. function:: obs_source_t *obs_filter_get_target(const obs_source_t *filter) If the source is a filter, returns the target source of the filter. The target source is the next source in the filter chain. Only guaranteed to be valid inside of the video_render, filter_audio, filter_video, and filter_remove callbacks. --------------------- .. function:: void obs_source_default_render(obs_source_t *source) Can be used by filters to directly render a non-async parent source without any filter processing. --------------------- .. function:: void obs_source_filter_add(obs_source_t *source, obs_source_t *filter) void obs_source_filter_remove(obs_source_t *source, obs_source_t *filter) Adds/removes a filter to/from a source. --------------------- .. function:: void obs_source_filter_set_order(obs_source_t *source, obs_source_t *filter, enum obs_order_movement movement) Modifies the order of a specific filter. :param movement: | Can be one of the following: | OBS_ORDER_MOVE_UP | OBS_ORDER_MOVE_DOWN | OBS_ORDER_MOVE_TOP | OBS_ORDER_MOVE_BOTTOM --------------------- Functions used by filters ------------------------- .. function:: bool obs_source_process_filter_begin(obs_source_t *filter, enum gs_color_format format, enum obs_allow_direct_render allow_direct) Default RGB filter handler for generic effect filters. Processes the filter chain and renders them to texture if needed, then the filter is drawn with. After calling this, set your parameters for the effect, then call obs_source_process_filter_end to draw the filter. :return: *true* if filtering should continue, *false* if the filter is bypassed for whatever reason --------------------- .. function:: bool obs_source_process_filter_begin_with_color_space(obs_source_t *filter, enum gs_color_format format, enum gs_color_space space, enum obs_allow_direct_render allow_direct) Similar to obs_source_process_filter_begin, but also set the active color space. :return: *true* if filtering should continue, *false* if the filter is bypassed for whatever reason --------------------- .. function:: void obs_source_process_filter_end(obs_source_t *filter, gs_effect_t *effect, uint32_t width, uint32_t height) Draws the filter using the effect's "Draw" technique. Before calling this function, first call obs_source_process_filter_begin and then set the effect parameters, and then call this function to finalize the filter. --------------------- .. function:: void obs_source_process_filter_tech_end(obs_source_t *filter, gs_effect_t *effect, uint32_t width, uint32_t height, const char *tech_name) Draws the filter with a specific technique in the effect. Before calling this function, first call obs_source_process_filter_begin and then set the effect parameters, and then call this function to finalize the filter. --------------------- .. function:: void obs_source_skip_video_filter(obs_source_t *filter) Skips the filter if the filter is invalid and cannot be rendered. --------------------- .. _transitions: Transitions ----------- .. function:: obs_source_t *obs_transition_get_source(obs_source_t *transition, enum obs_transition_target target) :param target: | OBS_TRANSITION_SOURCE_A - Source being transitioned from, or the current source if not transitioning | OBS_TRANSITION_SOURCE_B - Source being transitioned to :return: An incremented reference to the source or destination sources of the transition --------------------- .. function:: void obs_transition_clear(obs_source_t *transition) Clears the transition. --------------------- .. function:: obs_source_t *obs_transition_get_active_source(obs_source_t *transition) :return: An incremented reference to the currently active source of the transition --------------------- .. function:: bool obs_transition_start(obs_source_t *transition, enum obs_transition_mode mode, uint32_t duration_ms, obs_source_t *dest) Starts the transition with the desired destination source. :param mode: Currently only OBS_TRANSITION_MODE_AUTO :param duration_ms: Duration in milliseconds. If the transition has a fixed duration set by :c:func:`obs_transition_enable_fixed`, this parameter will have no effect :param dest: The destination source to transition to --------------------- .. function:: void obs_transition_set_size(obs_source_t *transition, uint32_t cx, uint32_t cy) void obs_transition_get_size(const obs_source_t *transition, uint32_t *cx, uint32_t *cy) Sets/gets the dimensions of the transition. --------------------- .. function:: void obs_transition_set_scale_type(obs_source_t *transition, enum obs_transition_scale_type type) enum obs_transition_scale_type obs_transition_get_scale_type( const obs_source_t *transition) Sets/gets the scale type for sources within the transition. :param type: | OBS_TRANSITION_SCALE_MAX_ONLY - Scale to aspect ratio, but only to the maximum size of each source | OBS_TRANSITION_SCALE_ASPECT - Always scale the sources, but keep aspect ratio | OBS_TRANSITION_SCALE_STRETCH - Scale and stretch the sources to the size of the transition --------------------- .. function:: void obs_transition_set_alignment(obs_source_t *transition, uint32_t alignment) uint32_t obs_transition_get_alignment(const obs_source_t *transition) Sets/gets the alignment used to draw the two sources within transition the transition. :param alignment: | Can be any bitwise OR combination of: | OBS_ALIGN_CENTER | OBS_ALIGN_LEFT | OBS_ALIGN_RIGHT | OBS_ALIGN_TOP | OBS_ALIGN_BOTTOM --------------------- Functions used by transitions ----------------------------- .. function:: void obs_transition_enable_fixed(obs_source_t *transition, bool enable, uint32_t duration_ms) bool obs_transition_fixed(obs_source_t *transition) Sets/gets whether the transition uses a fixed duration. Useful for certain types of transitions such as stingers. If this is set, the *duration_ms* parameter of :c:func:`obs_transition_start()` has no effect. --------------------- .. function:: float obs_transition_get_time(obs_source_t *transition) :return: The current transition time value (0.0f..1.0f) --------------------- .. function:: void obs_transition_video_render(obs_source_t *transition, obs_transition_video_render_callback_t callback) void obs_transition_video_render2(obs_source_t *transition, obs_transition_video_render_callback_t callback, gs_texture_t *placeholder_texture) Helper function used for rendering transitions. This function will render two distinct textures for source A and source B of the transition, allowing the ability to blend them together with a pixel shader in a desired manner. The *a* and *b* parameters of *callback* are automatically rendered textures of source A and source B, *t* is the time value (0.0f..1.0f), *cx* and *cy* are the current dimensions of the transition, and *data* is the implementation's private data. The *placeholder_texture* parameter allows a callback to receive a replacement that isn't the default transparent texture, including NULL if the caller desires. Relevant data types used with this function: .. code:: cpp typedef void (*obs_transition_video_render_callback_t)(void *data, gs_texture_t *a, gs_texture_t *b, float t, uint32_t cx, uint32_t cy); --------------------- .. function:: enum gs_color_space obs_transition_video_get_color_space(obs_source_t *transition) Figure out the color space that encompasses both child sources. The wider space wins. :return: The color space of the transition --------------------- .. function:: bool obs_transition_audio_render(obs_source_t *transition, uint64_t *ts_out, struct obs_source_audio_mix *audio, uint32_t mixers, size_t channels, size_t sample_rate, obs_transition_audio_mix_callback_t mix_a_callback, obs_transition_audio_mix_callback_t mix_b_callback) Helper function used for transitioning audio. Typically you'd call this in the obs_source_info.audio_render callback with its parameters, and use the mix_a_callback and mix_b_callback to determine the the audio fading of source A and source B. Relevant data types used with this function: .. code:: cpp typedef float (*obs_transition_audio_mix_callback_t)(void *data, float t); --------------------- .. function:: void obs_transition_swap_begin(obs_source_t *tr_dest, obs_source_t *tr_source) void obs_transition_swap_end(obs_source_t *tr_dest, obs_source_t *tr_source) Swaps two transitions. Call obs_transition_swap_begin, swap the source, then call obs_transition_swap_end when complete. This allows the ability to seamlessly swap two different transitions without it affecting the output. For example, if a transition is assigned to output channel 0, you'd call obs_transition_swap_begin, then you'd call obs_set_output_source with the new transition, then call :c:func:`obs_transition_swap_begin()`. .. --------------------------------------------------------------------------- .. _libobs/obs-source.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-source.h