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_reset_audio2(const struct obs_audio_info2 *oai)

Sets base audio output format/channels/samples/etc. Also allows the ability to set the maximum audio latency of OBS, and set whether the audio buffering is fixed or dynamically increasing.

When using fixed audio buffering, OBS will automatically buffer to the maximum audio latency on startup.

Maximum audio latency will clamp to the closest multiple of the audio output frames (which is typically 1024 audio frames).

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_info2 {
        uint32_t            samples_per_sec;
        enum speaker_layout speakers;

        uint32_t max_buffering_ms;
        bool fixed_buffering;
};

bool obs_get_video_info(struct obs_video_info *ovi)

Gets the current video settings.

Returns: false if no video

float obs_get_video_sdr_white_level(void)

Gets the current SDR white level.

Returns: SDR white level, 300.f if no video

float obs_get_video_hdr_nominal_peak_level(void)

Gets the current HDR nominal peak level.

Returns: HDR nominal peak level, 1000.f if no video

void obs_set_video_sdr_white_level(float sdr_white_level, float hdr_nominal_peak_level): Sets the current video levels.

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_scenes(bool (*enum_proc)(void*, obs_source_t*), void *param)

Enumerates all scenes.

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_scenes 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_source_t *obs_get_transition_by_name(const char *name)

Gets a transition by its name.

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

obs_scene_t *obs_get_scene_by_name(const char *name)

Gets a scene by its name.

Increments the scene reference counter, use obs_scene_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

bool obs_audio_monitoring_available(void)

Returns: Whether audio monitoring is supported and available on the current platform

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.

void obs_add_raw_audio_callback(size_t mix_idx, const struct audio_convert_info *conversion, audio_output_callback_t callback, void *param)

void obs_remove_raw_raw_callback(size_t track, audio_output_callback_t callback, void *param)

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

Parameters

mix_idx – Specifies audio track to get data from.
conversion – Specifies conversion requirements. Can be NULL.
callback – The callback that receives raw audio data.
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 macOS.)

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.