Source API Reference (obs_source_t)

Source Definition Structure (obs_source_info)

struct obs_source_info

Source definition structure.

const char *obs_source_info.id

Unique string identifier for the source (required).

uint32_t version

Source version (optional).

This is used when a source’s implementation is significantly modified and the previous version is deprecated, but is kept to prevent old sources from breaking.

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

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 obs_source_info.video_render callback in the source definition structure.

• OBS_SOURCE_AUDIO - Source has audio

  Use the 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 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 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: obs_source_info.mouse_click, obs_source_info.mouse_move, obs_source_info.mouse_wheel, obs_source_info.focus, and 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 obs_source_duplicate() or 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)

• OBS_SOURCE_REQUIRES_CANVAS - Source type requires a canvas.

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

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

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.

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

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

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.

Param data:

The implementation data associated with this source. This value can be null (e.g., when obs_get_source_properties() is called on the source type), make sure to handle this gracefully.

(Optional)

Return:

The properties of the source

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

void (*obs_source_info.activate)(void *data)

Called when the source has been activated in the main view (visible on stream/recording).

(Optional)

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)

void (*obs_source_info.show)(void *data)

Called when the source is visible on any display and/or on the main view.

(Optional)

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)

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

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 obs_source_process_filter_begin() and 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 obs_source_draw() to render the source’s texture.

Param effect:

This parameter is no longer used. Instead, call obs_source_draw()

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

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 obs_source_info.filter_audio callback or until the filter is removed/destroyed

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

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

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

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

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)

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

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)

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)

void (*obs_source_info.filter_add)(void *data, obs_source_t *source)

Called when the filter is added to a source.

(Optional)

Param data:

Filter data

Param source:

Source that the filter is being added to

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

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.

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.

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

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)

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

const char *(*obs_source_info.get_dark_icon)(void *type_data)

Gets the icon file path used for dark themes. Make sure icon_type is set to OBS_ICON_TYPE_CUSTOM.

const char *(*obs_source_info.get_light_icon)(void *type_data)

Gets the icon file path used for light themes. Make sure icon_type is set to OBS_ICON_TYPE_CUSTOM.

void (*obs_source_info.media_play_pause)(void *data, bool pause)

Called to pause or play media.

void (*obs_source_info.media_restart)(void *data)

Called to restart the media.

void (*obs_source_info.media_stop)(void *data)

Called to stop the media.

void (*obs_source_info.media_next)(void *data)

Called to go to the next media.

void (*obs_source_info.media_previous)(void *data)

Called to go to the previous media.

int64_t (*obs_source_info.media_get_duration)(void *data)

Called to get the media duration.

int64_t (*obs_source_info.media_get_time)(void *data)

Called to get the current time of the media.

void (*obs_source_info.media_set_time)(void *data, int64_t milliseconds)

Called to set the media time.

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

obs_missing_files_t *(*missing_files)(void *data)

Called to get the missing files of the source.

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

Common Source Signals

The following signals are defined for every source type:

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 obs_source_remove() function is called on the source.

update (ptr source)

Called when the source’s settings have been updated.

Added in version 29.0.0.

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 to signal to any properties view (or other users of the source’s obs_properties_t) that the presentable properties of the source have changed and should be re-queried via obs_source_properties. Does not mean that the source’s settings (as configured by the user) have changed. For that, use the update signal instead.

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.

audio_activate (ptr source)

Called when the source’s audio becomes active.

audio_deactivate (ptr source)

Called when the source’s audio becomes inactive.

filter_add (ptr source, ptr filter)

Called when a filter has been added to the source.

Added in version 30.0.

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 (ptr source)

Called when media has started.

media_ended (ptr source)

Called when media has ended.

media_pause (ptr source)

Called when media has been paused.

media_play (ptr source)

Called when media starts playing.

media_restart (ptr source)

Called when the playing of media has been restarted.

media_stopped (ptr source)

Called when the playing of media has been stopped.

media_next (ptr source)

Called when the media source switches to the next media.

media_previous (ptr source)

Called when the media source switches to the previous media.

Source-specific Signals

slide_changed (int index, string path)

Called when the source’s currently displayed image changes.

Defined by:

• Image Slide Show

hooked (ptr source, string title, string class, string executable)

Called when the source successfully captures an existing window.

Defined by:

• Window Capture (Windows)

• Game Capture (Windows)

• Application Audio Output Capture (Windows)

hooked (ptr source, string name, string class)

Called when the source successfully captures an existing window.

Defined by:

• Window Capture (Xcomposite)

unhooked (ptr source)

Called when the source stops capturing.

Defined by:

• Window Capture (Windows)

• Game Capture (Windows)

• Application Audio Output Capture (Windows)

• Window Capture (Xcomposite)

Source-specific Procedures

The following procedures are defined for specific sources only:

current_index (out int current_index)

Returns the index of the currently displayed image in the slideshow.

Defined by:

• Image Slide Show

total_files (out int total_files)

Returns the total number of image files in the slideshow.

Defined by:

• Image Slide Show

get_hooked (out bool hooked, out string title, out string class, out string executable)

Returns whether the source is currently capturing a window and if yes, which.

Defined by:

• Window Capture (Windows)

• Game Capture (Windows)

• Application audio output capture (Windows)

get_hooked (out bool hooked, out string name, out string class)

Returns whether the source is currently capturing a window and if yes, which.

Defined by:

• Window Capture (Xcomposite)

get_metadata (in string tag_id, out string tag_data)

For a given metadata tag, returns the data associated with it.

Defined by:

• VLC Video Source

restart ()

Restarts the media.

Defined by:

• Media Source

get_duration (out int duration)

Returns the total duration of the media file, in nanoseconds.

Defined by:

• Media Source

get_nb_frames (out int num_frames)

Returns the total number of frames in the media file.

Defined by:

• Media Source

activate (in bool active)

Activates or deactivates the device.

Defined by:

• Video Capture Device Source (Windows)

General Source Functions

void obs_register_source(struct obs_source_info *info)

Registers a source type. Typically used in obs_module_load() or in the program’s initialization phase.

const char *obs_source_get_display_name(const char *id)

Calls the obs_source_info.get_name callback to get the translated display name of a source type.

Parameters:

• id – The source type string identifier

Returns:

The translated display name of a source type

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.

Parameters:

• id – The source type string identifier

• name – The desired name of the source. If this is not unique, it will be made to be unique

• settings – The settings for the source, or NULL if none

• hotkey_data – Saved hotkey data for the source, or NULL if none

Returns:

A reference to the newly created source, or NULL if failed

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 obs_enum_sources(), and is not saved by 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 obs_enum_sources() and obs_save_sources() should not exist in the back-end.

Parameters:

• id – The source type string identifier

• name – The desired name of the source. For private sources, this does not have to be unique, and can additionally be NULL if desired

• settings – The settings for the source, or NULL if none

Returns:

A reference to the newly created source, or NULL if failed

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. Either way, release with obs_source_release().

Parameters:

• source – The source to duplicate

• 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

• create_private – If true, the new source will be a private source if fully duplicated

Returns:

A new source reference

obs_source_t *obs_source_get_ref(obs_source_t *source)

Returns an incremented reference if still valid, otherwise returns NULL. Use obs_source_release() to release it.

void obs_source_release(obs_source_t *source)

Releases a reference to a source. When the last reference is released, the source is destroyed.

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 an incremented weak reference from a strong source reference, or an incremented strong source reference from a weak reference. If the source is destroyed, obs_weak_source_get_source will return NULL. Release with obs_weak_source_release() or obs_source_release(), respectively.

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.

void obs_source_remove(obs_source_t *source)

Notifies all reference holders of the source (via obs_source_removed()) that the source should be released.

bool obs_source_removed(const obs_source_t *source)

Returns:

true if the source should be released

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.

uint32_t obs_source_get_output_flags(const obs_source_t *source)

uint32_t obs_get_source_output_flags(const char *id)

Returns:

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 obs_source_info.output_flags for more information.

obs_data_t *obs_get_source_defaults(const char *id)

Calls obs_source_info.get_defaults to get the defaults settings of the source type.

Returns:

The default settings for a source type

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.

Returns:

The properties list for a specific existing source. Free with obs_properties_destroy()

bool obs_source_configurable(const obs_source_t *source)

bool obs_is_source_configurable(const char *id)

Returns:

true if the the source has custom properties, false otherwise

void obs_source_update(obs_source_t *source, obs_data_t *settings)

Updates the settings for a source and calls the obs_source_info.update callback of the source. If the source is a video source, the obs_source_info.update will be not be called immediately; instead, it will be deferred to the video thread to prevent threading issues.

void obs_source_reset_settings(obs_source_t *source, obs_data_t *settings)

Same as obs_source_update(), but clears existing settings first.

void obs_source_video_render(obs_source_t *source)

Renders a video source. This will call the obs_source_info.video_render callback of the source.

uint32_t obs_source_get_width(obs_source_t *source)

uint32_t obs_source_get_height(obs_source_t *source)

Calls the obs_source_info.get_width or 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.

Returns:

The width or height of the source

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

Returns:

The color space of the source

bool obs_source_get_texcoords_centered(obs_source_t *source)

Hints whether or not the source will blend texels.

Returns:

Whether or not the source will blend texels

obs_data_t *obs_source_get_settings(const obs_source_t *source)

Returns:

The settings string for a source. The reference counter of the returned settings data is incremented, so obs_data_release() must be called when the settings are no longer used

const char *obs_source_get_name(const obs_source_t *source)

Returns:

The name of the source

const char *obs_source_get_uuid(const obs_source_t *source)

Returns:

The UUID of the source

Added in version 29.1.

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.

enum obs_source_type obs_source_get_type(const obs_source_t *source)

Returns:

OBS_SOURCE_TYPE_INPUT for inputs

OBS_SOURCE_TYPE_FILTER for filters

OBS_SOURCE_TYPE_TRANSITION for transitions

OBS_SOURCE_TYPE_SCENE for scenes

bool obs_source_is_scene(const obs_source_t *source)

Returns:

true if the source is a scene

bool obs_source_is_group(const obs_source_t *source)

Returns:

true if the source is a group

const char *obs_source_get_id(const obs_source_t *source)

return:

The source’s type identifier string. If the source is versioned, “_vN” is appended at the end, where “N” is the source’s version.

---

const char *obs_source_get_unversioned_id(const obs_source_t *source)

Returns:

The source’s unversioned type identifier string.

signal_handler_t *obs_source_get_signal_handler(const obs_source_t *source)

Returns:

The source’s signal handler. Should not be manually freed, as its lifecycle is managed by libobs.

See the Common Source Signals for more information on signals that are available for sources.

proc_handler_t *obs_source_get_proc_handler(const obs_source_t *source)

Returns:

The procedure handler for a source. Should not be manually freed, as its lifecycle is managed by libobs.

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.

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.

enum speaker_layout obs_source_get_speaker_layout(obs_source_t *source)

Gets the current speaker layout.

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.

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.

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 (i.e. audio tracks) 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.

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.

Parameters:

• 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

void obs_source_set_audio_active(obs_source_t *source, bool active)

bool obs_source_audio_active(const obs_source_t *source)

Sets/gets the audio active status (controls whether the source is shown in the mixer).

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:

typedef void (*obs_source_enum_proc_t)(obs_source_t *parent,
                obs_source_t *child, void *param);

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.

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.

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.

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.

bool obs_source_active(const obs_source_t *source)

Returns:

true if active, false if not. A source is only considered active if it’s being shown on the final mix

bool obs_source_showing(const obs_source_t *source)

Returns:

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

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.

void obs_source_set_flags(obs_source_t *source, uint32_t flags)

uint32_t obs_source_get_flags(const obs_source_t *source)

Parameters:

• flags – OBS_SOURCE_FLAG_FORCE_MONO Forces audio to mono

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:

typedef void (*obs_source_enum_proc_t)(obs_source_t *parent,
                obs_source_t *child, void *param);

obs_source_t *obs_source_get_filter_by_name(obs_source_t *source, const char *name)

Returns:

The desired filter, or NULL if not found. The reference of the filter is incremented

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.

void obs_source_copy_single_filter(obs_source_t *dst, obs_source_t *filter)

Copies the filter from the source to the destination. If a filter by the same name already exists in the destination source, the newer filter will be given a unique name.

size_t obs_source_filter_count(const obs_source_t *source)

Returns the number of filters the source has.

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.

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.

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:

typedef void (*obs_source_audio_capture_t)(void *param, obs_source_t *source,
                const struct audio_data *audio_data, bool muted);

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.

Parameters:

• 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

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.

Parameters:

• order –

  OBS_DEINTERLACE_FIELD_ORDER_TOP - Start from top

  OBS_DEINTERLACE_FIELD_ORDER_BOTTOM - Start from bottom

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. Use obs_data_release() to release it.

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.

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.

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.

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.

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.

enum obs_icon_type obs_source_get_icon_type(const char *id)

Calls the obs_source_info.icon_type to get the icon type.

const char *obs_source_get_dark_icon(const char *id)

Calls the obs_source_info.get_dark_icon to get the dark icon.

const char *obs_source_get_light_icon(const char *id)

Calls the obs_source_info.get_light_icon to get the light icon.

void obs_source_media_play_pause(obs_source_t *source, bool pause)

Calls the obs_source_info.media_play_pause to pause or play media.

void obs_source_media_restart(obs_source_t *source)

Calls the obs_source_info.media_restart to restart the media.

void obs_source_media_stop(obs_source_t *source)

Calls the obs_source_info.media_stop to stop the media.

void obs_source_media_next(obs_source_t *source)

Calls the obs_source_info.media_next to go to the next media.

void obs_source_media_previous(obs_source_t *source)

Calls the obs_source_info.media_previous to go to the previous media.

int64_t obs_source_media_get_duration(obs_source_t *source)

Calls the obs_source_info.media_get_duration to get the media duration in milliseconds.

int64_t obs_source_media_get_time(obs_source_t *source)

void obs_source_media_set_time(obs_source_t *source, int64_t ms)

Calls the obs_source_info.media_get_time or obs_source_info.media_set_time to get/set the current time (in milliseconds) of the media. Will return 0 for non-media sources.

enum obs_media_state obs_source_media_get_state(obs_source_t *source)

Calls the obs_source_info.media_get_state to get the state of the media.

void obs_source_media_started(obs_source_t *source)

Emits a media_started signal.

void obs_source_media_ended(obs_source_t *source)

Emits a media_ended signal.

obs_canvas_t *obs_source_get_canvas(const obs_source_t *source)

Get canvas this source belongs to (reference incremented)

Functions used by sources

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.

Parameters:

• color_matrix – The color matrix. Assigns to the ‘color_matrix’ effect variable.

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

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

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

Parameters:

• image – The sprite texture to draw. Assigns to the ‘image’ variable of the current effect.

• x – X position of the sprite.

• y – Y position of the sprite.

• cx – Width of the sprite. If 0, uses the texture width.

• cy – Height of the sprite. If 0, uses the texture height.

• flip – Specifies whether to flip the image vertically.

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:

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

        /* planar 4:2:2 format, 10 bpp */
        VIDEO_FORMAT_I210,

        /* planar 4:4:4 format, 12 bpp */
        VIDEO_FORMAT_I412,

        /* planar 4:4:4:4 format, 12 bpp */
        VIDEO_FORMAT_YA2L,

        /* planar 4:2:2 format, 16 bpp */
        VIDEO_FORMAT_P216, /* two-plane, luma and packed chroma */

        /* planar 4:4:4 format, 16 bpp */
        VIDEO_FORMAT_P416, /* two-plane, luma and packed chroma */

        /* packed 4:2:2 format, 10 bpp */
        VIDEO_FORMAT_V210,

        /* packed uncompressed 10-bit format */
        VIDEO_FORMAT_R10L,
};

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 */
};

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.

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.

void obs_source_show_preloaded_video(obs_source_t *source)

Shows any preloaded video frame.

void obs_source_output_audio(obs_source_t *source, const struct obs_source_audio *audio)

Outputs audio data.

void obs_source_update_properties(obs_source_t *source)

Signals to any currently opened properties views (or other users of the source’s obs_properties_t) that the source’s presentable properties have changed and that the view should be updated.

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.

Returns:

true if source can be added, false if it causes recursion

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

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. Does not increment the reference.

Only guaranteed to be valid inside of the video_render, filter_audio, filter_video, filter_add, and filter_remove callbacks.

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. Does not increment the reference.

Only guaranteed to be valid inside of the video_render, filter_audio, filter_video, and filter_remove callbacks.

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.

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.

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.

Parameters:

• movement –

  Can be one of the following:

  OBS_ORDER_MOVE_UP

  OBS_ORDER_MOVE_DOWN

  OBS_ORDER_MOVE_TOP

  OBS_ORDER_MOVE_BOTTOM

void obs_source_filter_set_index(obs_source_t *source, obs_source_t *filter, size_t index)

Moves a filter to the specified index in the filters array.

Parameters:

• index –

  The index to move the filter to.

Added in version 30.0.

int obs_source_filter_get_index(obs_source_t *source, obs_source_t *filter)

Gets the index of the specified filter.

Returns:

Index of the filter or -1 if it is invalid/not found.

Added in version 30.0.

Functions used by filters

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.

Returns:

true if filtering should continue, false if the filter is bypassed for whatever reason

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.

Returns:

true if filtering should continue, false if the filter is bypassed for whatever reason

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.

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.

void obs_source_skip_video_filter(obs_source_t *filter)

Skips the filter if the filter is invalid and cannot be rendered.

Transitions

obs_source_t *obs_transition_get_source(obs_source_t *transition, enum obs_transition_target target)

Parameters:

• target –

  OBS_TRANSITION_SOURCE_A - Source being transitioned from, or the current source if not transitioning

  OBS_TRANSITION_SOURCE_B - Source being transitioned to

Returns:

An incremented reference to the source or destination sources of the transition. Use obs_source_release() to release it.

void obs_transition_clear(obs_source_t *transition)

Clears the transition.

obs_source_t *obs_transition_get_active_source(obs_source_t *transition)

Returns:

An incremented reference to the currently active source of the transition. Use obs_source_release() to release it.

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.

Parameters:

• mode – Currently only OBS_TRANSITION_MODE_AUTO

• duration_ms – Duration in milliseconds. If the transition has a fixed duration set by obs_transition_enable_fixed(), this parameter will have no effect

• dest – The destination source to transition to

void obs_transition_is_active(obs_source_t *transition)

Returns:

true if the transition is currently transitioning, false otherwise.

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.

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.

Parameters:

• 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

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.

Parameters:

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

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 obs_transition_start() has no effect.