OBS Core API Reference

#include <obs.h>

Initialization, Shutdown, and Information

bool obs_startup(const char *locale, const char *module_config_path, profiler_name_store_t *store)

Initializes the OBS core context.

Parameters:
  • locale – The locale to use for modules (E.G. “en-US”)
  • module_config_path – Path to module config storage directory (or NULL if none)
  • store – The profiler name store for OBS to use or NULL
Returns:

false if already initialized or failed to initialize


void obs_shutdown(void)

Releases all data associated with OBS and terminates the OBS context.


bool obs_initialized(void)
Returns:true if the main OBS context has been initialized

uint32_t obs_get_version(void)
Returns:The current core version

const char *obs_get_version_string(void)
Returns:The current core version string

void obs_set_locale(const char *locale)

Sets a new locale to use for modules. This will call obs_module_set_locale for each module with the new locale.

Parameters:
  • locale – The locale to use for modules

const char *obs_get_locale(void)
Returns:The current locale

profiler_name_store_t *obs_get_profiler_name_store(void)
Returns:The profiler name store (see util/profiler.h) used by OBS, which is either a name store passed to obs_startup, an internal name store, or NULL in case obs_initialized() returns false.

int obs_reset_video(struct obs_video_info *ovi)

Sets base video output base resolution/fps/format.

Note: This data cannot be changed if an output is currently active.

Note: The graphics module cannot be changed without fully destroying the OBS context.

Parameters:
  • ovi – Pointer to an obs_video_info structure containing the specification of the graphics subsystem,
Returns:

OBS_VIDEO_SUCCESS - Success
OBS_VIDEO_NOT_SUPPORTED - The adapter lacks capabilities
OBS_VIDEO_INVALID_PARAM - A parameter is invalid
OBS_VIDEO_CURRENTLY_ACTIVE - Video is currently active
OBS_VIDEO_MODULE_NOT_FOUND - The graphics module is not found
OBS_VIDEO_FAIL - Generic failure

Relevant data types used with this function:

struct obs_video_info {
        /**
         * Graphics module to use (usually "libobs-opengl" or "libobs-d3d11")
         */
        const char          *graphics_module;

        uint32_t            fps_num;       /**< Output FPS numerator */
        uint32_t            fps_den;       /**< Output FPS denominator */

        uint32_t            base_width;    /**< Base compositing width */
        uint32_t            base_height;   /**< Base compositing height */

        uint32_t            output_width;  /**< Output width */
        uint32_t            output_height; /**< Output height */
        enum video_format   output_format; /**< Output format */

        /** Video adapter index to use (NOTE: avoid for optimus laptops) */
        uint32_t            adapter;

        /** Use shaders to convert to different color formats */
        bool                gpu_conversion;

        enum video_colorspace colorspace;  /**< YUV type (if YUV) */
        enum video_range_type range;       /**< YUV range (if YUV) */

        enum obs_scale_type scale_type;    /**< How to scale if scaling */
};

bool obs_reset_audio(const struct obs_audio_info *oai)

Sets base audio output format/channels/samples/etc.

Note: Cannot reset base audio if an output is currently active.

Returns:true if successful, false otherwise

Relevant data types used with this function:

struct obs_audio_info {
        uint32_t            samples_per_sec;
        enum speaker_layout speakers;
};

bool obs_get_video_info(struct obs_video_info *ovi)

Gets the current video settings.

Returns:false if no video

bool obs_get_audio_info(struct obs_audio_info *oai)

Gets the current audio settings.

Returns:false if no audio

Libobs Objects

bool obs_enum_source_types(size_t idx, const char **id)

Enumerates all source types (inputs, filters, transitions, etc).


bool obs_enum_input_types(size_t idx, const char **id)

Enumerates all available inputs source types.

Inputs are general source inputs (such as capture sources, device sources, etc).


bool obs_enum_filter_types(size_t idx, const char **id)

Enumerates all available filter source types.

Filters are sources that are used to modify the video/audio output of other sources.


bool obs_enum_transition_types(size_t idx, const char **id)

Enumerates all available transition source types.

Transitions are sources used to transition between two or more other sources.


bool obs_enum_output_types(size_t idx, const char **id)

Enumerates all available output types.


bool obs_enum_encoder_types(size_t idx, const char **id)

Enumerates all available encoder types.


bool obs_enum_service_types(size_t idx, const char **id)

Enumerates all available service types.


void obs_enum_sources(bool (*enum_proc)(void*, obs_source_t*), void *param)

Enumerates all input sources.

Callback function returns true to continue enumeration, or false to end enumeration.

Use obs_source_get_ref() or obs_source_get_weak_source() if you want to retain a reference after obs_enum_sources finishes.


void obs_enum_outputs(bool (*enum_proc)(void*, obs_output_t*), void *param)

Enumerates outputs.


void obs_enum_encoders(bool (*enum_proc)(void*, obs_encoder_t*), void *param)

Enumerates encoders.


obs_source_t *obs_get_source_by_name(const char *name)

Gets a source by its name.

Increments the source reference counter, use obs_source_release() to release it when complete.


obs_output_t *obs_get_output_by_name(const char *name)

Gets an output by its name.

Increments the output reference counter, use obs_output_release() to release it when complete.


obs_encoder_t *obs_get_encoder_by_name(const char *name)

Gets an encoder by its name.

Increments the encoder reference counter, use obs_encoder_release() to release it when complete.


obs_service_t *obs_get_service_by_name(const char *name)

Gets an service by its name.

Increments the service reference counter, use obs_service_release() to release it when complete.


obs_data_t *obs_save_source(obs_source_t *source)
Returns:A new reference to a source’s saved data

obs_source_t *obs_load_source(obs_data_t *data)
Returns:A source created from saved data

void obs_load_sources(obs_data_array_t *array, obs_load_source_cb cb, void *private_data)

Helper function to load active sources from a data array.

Relevant data types used with this function:

typedef void (*obs_load_source_cb)(void *private_data, obs_source_t *source);

obs_data_array_t *obs_save_sources(void)
Returns:A data array with the saved data of all active sources

obs_data_array_t *obs_save_sources_filtered(obs_save_source_filter_cb cb, void *data)
Returns:A data array with the saved data of all active sources, filtered by the cb function

Relevant data types used with this function:

typedef bool (*obs_save_source_filter_cb)(void *data, obs_source_t *source);

Video, Audio, and Graphics

void obs_enter_graphics(void)

Helper function for entering the OBS graphics context.


void obs_leave_graphics(void)

Helper function for leaving the OBS graphics context.


audio_t *obs_get_audio(void)
Returns:The main audio output handler for this OBS context

video_t *obs_get_video(void)
Returns:The main video output handler for this OBS context

void obs_set_output_source(uint32_t channel, obs_source_t *source)

Sets the primary output source for a channel.


obs_source_t *obs_get_output_source(uint32_t channel)

Gets the primary output source for a channel and increments the reference counter for that source. Use obs_source_release() to release.


gs_effect_t *obs_get_base_effect(enum obs_base_effect effect)

Returns a commoinly used base effect.

Parameters:
  • effect
    Can be one of the following values:
    OBS_EFFECT_DEFAULT - RGB/YUV
    OBS_EFFECT_DEFAULT_RECT - RGB/YUV (using texture_rect)
    OBS_EFFECT_OPAQUE - RGB/YUV (alpha set to 1.0)
    OBS_EFFECT_SOLID - RGB/YUV (solid color only)
    OBS_EFFECT_BICUBIC - Bicubic downscale
    OBS_EFFECT_LANCZOS - Lanczos downscale
    OBS_EFFECT_BILINEAR_LOWRES - Bilinear low resolution downscale
    OBS_EFFECT_PREMULTIPLIED_ALPHA - Premultiplied alpha

void obs_render_main_view(void)

Renders the main view.

Note: This function is deprecated.


void obs_render_main_texture(void)

Renders the main output texture. Useful for rendering a preview pane of the main output.


void obs_set_master_volume(float volume)

Sets the master user volume.


float obs_get_master_volume(void)
Returns:The master user volume

void obs_enum_audio_monitoring_devices(obs_enum_audio_device_cb cb, void *data)

Enumerates audio devices which can be used for audio monitoring.

Relevant data types used with this function:

typedef bool (*obs_enum_audio_device_cb)(void *data, const char *name, const char *id);

bool obs_set_audio_monitoring_device(const char *name, const char *id)

Sets the current audio device for audio monitoring.


void obs_get_audio_monitoring_device(const char **name, const char **id)

Gets the current audio device for audio monitoring.


void obs_add_main_render_callback(void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param)
void obs_remove_main_render_callback(void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param)

Adds/removes a main rendering callback. Allows custom rendering to the main stream/recording output.


void obs_add_raw_video_callback(const struct video_scale_info *conversion, void (*callback)(void *param, struct video_data *frame), void *param)
void obs_remove_raw_video_callback(void (*callback)(void *param, struct video_data *frame), void *param)

Adds/removes a raw video callback. Allows the ability to obtain raw video frames without necessarily using an output.

Parameters:
  • conversion – Specifies conversion requirements. Can be NULL.
  • callback – The callback that receives raw video frames.
  • param – The private data associated with the callback.

Primary signal/procedure handlers

signal_handler_t *obs_get_signal_handler(void)
Returns:The primary obs signal handler

See Core OBS Signals for more information on core signals.


proc_handler_t *obs_get_proc_handler(void)
Returns:The primary obs procedure handler

Core OBS Signals

source_create (ptr source)

Called when a source has been created.

source_destroy (ptr source)

Called when a source has been destroyed.

source_remove (ptr source)

Called when a source has been removed (obs_source_remove() has been called on the source).

source_save (ptr source)

Called when a source is being saved.

source_load (ptr source)

Called when a source is being loaded.

source_activate (ptr source)

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

source_deactivate (ptr source)

Called when a source has been deactivated from the main view (no longer visible on stream/recording).

source_show (ptr source)

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

source_hide (ptr source)

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

source_rename (ptr source, string new_name, string prev_name)

Called when a source has been renamed.

source_volume (ptr source, in out float volume)

Called when a source’s volume has changed.

source_transition_start (ptr source)

Called when a transition has started its transition.

source_transition_video_stop (ptr source)

Called when a transition has stopped its video transitioning.

source_transition_stop (ptr source)

Called when a transition has stopped its transition.

channel_change (int channel, in out ptr source, ptr prev_source)

Called when obs_set_output_source() has been called.

master_volume (in out float volume)

Called when the master volume has changed.

hotkey_layout_change ()

Called when the hotkey layout has changed.

hotkey_register (ptr hotkey)

Called when a hotkey has been registered.

hotkey_unregister (ptr hotkey)

Called when a hotkey has been unregistered.

hotkey_bindings_changed (ptr hotkey)

Called when a hotkey’s bindings has changed.

Displays

obs_display_t *obs_display_create(const struct gs_init_data *graphics_data)

Adds a new window display linked to the main render pipeline. This creates a new swap chain which updates every frame.

(Important note: do not use more than one display widget within the hierarchy of the same base window; this will cause presentation stalls on Macs.)

Parameters:
  • graphics_data – The swap chain initialization data
Returns:

The new display context, or NULL if failed

Relevant data types used with this function:

enum gs_color_format {
        [...]
        GS_RGBA,
        GS_BGRX,
        GS_BGRA,
        GS_RGBA16F,
        GS_RGBA32F,
        [...]
};

enum gs_zstencil_format {
        GS_ZS_NONE,
        GS_Z16,
        GS_Z24_S8,
        GS_Z32F,
        GS_Z32F_S8X24
};

struct gs_window {
#if defined(_WIN32)
        void                    *hwnd;
#elif defined(__APPLE__)
        __unsafe_unretained id  view;
#elif defined(__linux__) || defined(__FreeBSD__)
        uint32_t                id;
        void                    *display;
#endif
};

struct gs_init_data {
        struct gs_window        window;
        uint32_t                cx, cy;
        uint32_t                num_backbuffers;
        enum gs_color_format    format;
        enum gs_zstencil_format zsformat;
        uint32_t                adapter;
};

void obs_display_destroy(obs_display_t *display)

Destroys a display context.


void obs_display_resize(obs_display_t *display, uint32_t cx, uint32_t cy)

Changes the size of a display context.


void obs_display_add_draw_callback(obs_display_t *display, void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param)

Adds a draw callback for a display context, which will be called whenever the display is rendered.

Parameters:
  • display – The display context
  • draw – The draw callback which is called each time a frame updates
  • param – The user data to be associated with this draw callback

void obs_display_remove_draw_callback(obs_display_t *display, void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param)

Removes a draw callback for a display context.


void obs_display_set_enabled(obs_display_t *display, bool enable)

Enables/disables a display context.


bool obs_display_enabled(obs_display_t *display)
Returns:true if the display is enabled, false otherwise

void obs_display_set_background_color(obs_display_t *display, uint32_t color)

Sets the background (clear) color for the display context.