OBS Core API Reference — OBS Studio 32.1.0 documentation

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

For scripting, use obs_enum_sources().

void obs_enum_scenes(bool (*enum_proc)(void*, obs_source_t*), void *param)

Enumerates all scenes. Use obs_scene_from_source() if the scene is needed as an obs_scene_t. The order that they are enumerated should not be relied on. If one intends to enumerate the scenes in the order presented by the OBS Studio Frontend, use obs_frontend_get_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.

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

Use obs_output_get_ref() or obs_output_get_weak_output() if you want to retain a reference after obs_enum_outputs finishes.

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

Enumerates encoders.

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

Use obs_encoder_get_ref() or obs_encoder_get_weak_encoder() if you want to retain a reference after obs_enum_encoders finishes.

void obs_enum_canvases(bool (*enum_proc)(void*, obs_canvas_t*), void *param)

Enumerates canvases.

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

Use obs_canvas_get_ref() or obs_canvas_get_weak_canvas() if you want to retain a reference after obs_enum_canvases finishes.

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_source_by_uuid(const char *uuid)

Gets a source by its UUID.

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

Added in version 29.1.

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_source_t *obs_get_transition_by_uuid(const char *uuid)

Gets a transition by its UUID.

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

Added in version 29.1.

Deprecated since version 31.1: Use obs_get_source_by_uuid() instead.

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_canvas_t *obs_get_canvas_by_name(const char *name)

Get a canvas by its name.

Increments the canvas reference counter, use obs_canvas_release() to release it when complete.

obs_canvas_t *obs_get_canvas_by_uuid(const char *uuid)

Get a canvas by its UUID.

Increments the canvas reference counter, use obs_canvas_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. Use obs_data_release() to release it when complete.

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 commonly 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_texture(void): Renders the main output texture. Useful for rendering a preview pane of the main output.

bool obs_audio_monitoring_available(void)

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

void obs_reset_audio_monitoring(void)

Resets all audio monitoring devices.

Added in version 30.1.

void obs_enum_audio_monitoring_devices(obs_enum_audio_device_cb cb, void *data)

Enumerates audio devices which can be used for audio monitoring.

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

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.

For scripting (Lua only), use obs_add_main_render_callback() and obs_remove_main_render_callback().

void obs_add_main_rendered_callback(void (*rendered)(void *param), void *param)

void obs_remove_main_rendered_callback(void (*rendered)(void *param), void *param)

Adds/removes a main rendered callback. Allows using the result of the main stream/recording output.

Added in version 29.1.

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. Should not be manually freed, as its lifecycle is managed by libobs.

See Core OBS Signals for more information on core signals.

proc_handler_t *obs_get_proc_handler(void)

Returns:: The primary obs procedure handler. Should not be manually freed, as its lifecycle is managed by libobs.

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

Called when a source’s settings have been updated.

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

Called when a source’s audio becomes active.

source_audio_deactivate (ptr source)

Called when a source’s audio becomes inactive.

source_filter_add (ptr source, ptr filter)

Called when a filter is added to a source.

source_filter_remove (ptr source, ptr filter)

Called when a filter is removed from a source.

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.

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.

canvas_create (ptr canvas)

Called when a new public canvas has been created.

canvas_remove (ptr canvas)

canvas_destroy (ptr canvas)

Called when a public canvas is about to be destroyed.

canvas_video_reset (ptr canvas)

Called when a public canvas’s video mix has been reset after a call to obs_reset_video() or obs_canvas_reset_video().

canvas_rename (ptr canvas, string new_name, string prev_name)

Called when a public canvas has been renamed.

video_reset ()

Called when a the main OBS video has been reset.

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.

Views

obs_view_t *obs_view_create(void)

Returns:: A view context

void obs_view_destroy(obs_view_t *view): Destroys a view context.

void obs_view_render(obs_view_t *view): Renders the sources of this view context.

video_t *obs_view_add(obs_view_t *view)

Renders the sources of this view context.

Returns:: The main video output handler for the view context

video_t *obs_view_add2(obs_view_t *view, struct obs_video_info *ovi)

Adds a view to the main render loop, with custom video settings.

Returns:: The main video output handler for the view context

void obs_view_remove(obs_view_t *view): Removes a view from the main render loop.

void obs_view_set_source(obs_view_t *view, uint32_t channel, obs_source_t *source): Sets the source to be used for this view context.

obs_source_t *obs_view_get_source(obs_view_t *view, uint32_t channel)

Returns:: The source currently in use for this view context

void obs_view_enum_video_info(obs_view_t *view, bool (*enum_proc)(void*, struct obs_video_info*), void *param)

Enumerates all the video info of all mixes that use the specified mix.

Added in version 30.1.