1OBS Core API Reference 2====================== 3 4.. code:: cpp 5 6 #include <obs.h> 7 8 9.. _obs_init_shutdown_reference: 10 11Initialization, Shutdown, and Information 12----------------------------------------- 13 14.. function:: bool obs_startup(const char *locale, const char *module_config_path, profiler_name_store_t *store) 15 16 Initializes the OBS core context. 17 18 :param locale: The locale to use for modules 19 (E.G. "en-US") 20 :param module_config_path: Path to module config storage directory 21 (or *NULL* if none) 22 :param store: The profiler name store for OBS to use or NULL 23 :return: *false* if already initialized or failed 24 to initialize 25 26--------------------- 27 28.. function:: void obs_shutdown(void) 29 30 Releases all data associated with OBS and terminates the OBS context. 31 32--------------------- 33 34.. function:: bool obs_initialized(void) 35 36 :return: true if the main OBS context has been initialized 37 38--------------------- 39 40.. function:: uint32_t obs_get_version(void) 41 42 :return: The current core version 43 44--------------------- 45 46.. function:: const char *obs_get_version_string(void) 47 48 :return: The current core version string 49 50--------------------- 51 52.. function:: void obs_set_locale(const char *locale) 53 54 Sets a new locale to use for modules. This will call 55 obs_module_set_locale for each module with the new locale. 56 57 :param locale: The locale to use for modules 58 59--------------------- 60 61.. function:: const char *obs_get_locale(void) 62 63 :return: The current locale 64 65--------------------- 66 67.. function:: profiler_name_store_t *obs_get_profiler_name_store(void) 68 69 :return: The profiler name store (see util/profiler.h) used by OBS, 70 which is either a name store passed to obs_startup, an 71 internal name store, or NULL in case obs_initialized() 72 returns false. 73 74--------------------- 75 76.. function:: int obs_reset_video(struct obs_video_info *ovi) 77 78 Sets base video output base resolution/fps/format. 79 80 Note: This data cannot be changed if an output is currently active. 81 82 Note: The graphics module cannot be changed without fully destroying 83 the OBS context. 84 85 :param ovi: Pointer to an obs_video_info structure containing the 86 specification of the graphics subsystem, 87 :return: | OBS_VIDEO_SUCCESS - Success 88 | OBS_VIDEO_NOT_SUPPORTED - The adapter lacks capabilities 89 | OBS_VIDEO_INVALID_PARAM - A parameter is invalid 90 | OBS_VIDEO_CURRENTLY_ACTIVE - Video is currently active 91 | OBS_VIDEO_MODULE_NOT_FOUND - The graphics module is not found 92 | OBS_VIDEO_FAIL - Generic failure 93 94 Relevant data types used with this function: 95 96.. code:: cpp 97 98 struct obs_video_info { 99 /** 100 * Graphics module to use (usually "libobs-opengl" or "libobs-d3d11") 101 */ 102 const char *graphics_module; 103 104 uint32_t fps_num; /**< Output FPS numerator */ 105 uint32_t fps_den; /**< Output FPS denominator */ 106 107 uint32_t base_width; /**< Base compositing width */ 108 uint32_t base_height; /**< Base compositing height */ 109 110 uint32_t output_width; /**< Output width */ 111 uint32_t output_height; /**< Output height */ 112 enum video_format output_format; /**< Output format */ 113 114 /** Video adapter index to use (NOTE: avoid for optimus laptops) */ 115 uint32_t adapter; 116 117 /** Use shaders to convert to different color formats */ 118 bool gpu_conversion; 119 120 enum video_colorspace colorspace; /**< YUV type (if YUV) */ 121 enum video_range_type range; /**< YUV range (if YUV) */ 122 123 enum obs_scale_type scale_type; /**< How to scale if scaling */ 124 }; 125 126--------------------- 127 128.. function:: bool obs_reset_audio(const struct obs_audio_info *oai) 129 130 Sets base audio output format/channels/samples/etc. 131 132 Note: Cannot reset base audio if an output is currently active. 133 134 :return: *true* if successful, *false* otherwise 135 136 Relevant data types used with this function: 137 138.. code:: cpp 139 140 struct obs_audio_info { 141 uint32_t samples_per_sec; 142 enum speaker_layout speakers; 143 }; 144 145--------------------- 146 147.. function:: bool obs_get_video_info(struct obs_video_info *ovi) 148 149 Gets the current video settings. 150 151 :return: *false* if no video 152 153--------------------- 154 155.. function:: bool obs_get_audio_info(struct obs_audio_info *oai) 156 157 Gets the current audio settings. 158 159 :return: *false* if no audio 160 161--------------------- 162 163 164Libobs Objects 165-------------- 166 167.. function:: bool obs_enum_source_types(size_t idx, const char **id) 168 169 Enumerates all source types (inputs, filters, transitions, etc). 170 171--------------------- 172 173.. function:: bool obs_enum_input_types(size_t idx, const char **id) 174 175 Enumerates all available inputs source types. 176 177 Inputs are general source inputs (such as capture sources, device sources, 178 etc). 179 180--------------------- 181 182.. function:: bool obs_enum_filter_types(size_t idx, const char **id) 183 184 Enumerates all available filter source types. 185 186 Filters are sources that are used to modify the video/audio output of 187 other sources. 188 189--------------------- 190 191.. function:: bool obs_enum_transition_types(size_t idx, const char **id) 192 193 Enumerates all available transition source types. 194 195 Transitions are sources used to transition between two or more other 196 sources. 197 198--------------------- 199 200.. function:: bool obs_enum_output_types(size_t idx, const char **id) 201 202 Enumerates all available output types. 203 204--------------------- 205 206.. function:: bool obs_enum_encoder_types(size_t idx, const char **id) 207 208 Enumerates all available encoder types. 209 210--------------------- 211 212.. function:: bool obs_enum_service_types(size_t idx, const char **id) 213 214 Enumerates all available service types. 215 216--------------------- 217 218.. function:: void obs_enum_sources(bool (*enum_proc)(void*, obs_source_t*), void *param) 219 220 Enumerates all input sources. 221 222 Callback function returns true to continue enumeration, or false to end 223 enumeration. 224 225 Use :c:func:`obs_source_get_ref()` or 226 :c:func:`obs_source_get_weak_source()` if you want to retain a 227 reference after obs_enum_sources finishes. 228 229--------------------- 230 231.. function:: void obs_enum_scenes(bool (*enum_proc)(void*, obs_source_t*), void *param) 232 233 Enumerates all scenes. 234 235 Callback function returns true to continue enumeration, or false to end 236 enumeration. 237 238 Use :c:func:`obs_source_get_ref()` or 239 :c:func:`obs_source_get_weak_source()` if you want to retain a 240 reference after obs_enum_scenes finishes. 241 242--------------------- 243 244.. function:: void obs_enum_outputs(bool (*enum_proc)(void*, obs_output_t*), void *param) 245 246 Enumerates outputs. 247 248--------------------- 249 250.. function:: void obs_enum_encoders(bool (*enum_proc)(void*, obs_encoder_t*), void *param) 251 252 Enumerates encoders. 253 254--------------------- 255 256.. function:: obs_source_t *obs_get_source_by_name(const char *name) 257 258 Gets a source by its name. 259 260 Increments the source reference counter, use 261 :c:func:`obs_source_release()` to release it when complete. 262 263--------------------- 264 265.. function:: obs_output_t *obs_get_output_by_name(const char *name) 266 267 Gets an output by its name. 268 269 Increments the output reference counter, use 270 :c:func:`obs_output_release()` to release it when complete. 271 272--------------------- 273 274.. function:: obs_encoder_t *obs_get_encoder_by_name(const char *name) 275 276 Gets an encoder by its name. 277 278 Increments the encoder reference counter, use 279 :c:func:`obs_encoder_release()` to release it when complete. 280 281--------------------- 282 283.. function:: obs_service_t *obs_get_service_by_name(const char *name) 284 285 Gets an service by its name. 286 287 Increments the service reference counter, use 288 :c:func:`obs_service_release()` to release it when complete. 289 290--------------------- 291 292.. function:: obs_data_t *obs_save_source(obs_source_t *source) 293 294 :return: A new reference to a source's saved data 295 296--------------------- 297 298.. function:: obs_source_t *obs_load_source(obs_data_t *data) 299 300 :return: A source created from saved data 301 302--------------------- 303 304.. function:: void obs_load_sources(obs_data_array_t *array, obs_load_source_cb cb, void *private_data) 305 306 Helper function to load active sources from a data array. 307 308 Relevant data types used with this function: 309 310.. code:: cpp 311 312 typedef void (*obs_load_source_cb)(void *private_data, obs_source_t *source); 313 314--------------------- 315 316.. function:: obs_data_array_t *obs_save_sources(void) 317 318 :return: A data array with the saved data of all active sources 319 320--------------------- 321 322.. function:: obs_data_array_t *obs_save_sources_filtered(obs_save_source_filter_cb cb, void *data) 323 324 :return: A data array with the saved data of all active sources, 325 filtered by the *cb* function 326 327 Relevant data types used with this function: 328 329.. code:: cpp 330 331 typedef bool (*obs_save_source_filter_cb)(void *data, obs_source_t *source); 332 333--------------------- 334 335 336Video, Audio, and Graphics 337-------------------------- 338 339.. function:: void obs_enter_graphics(void) 340 341 Helper function for entering the OBS graphics context. 342 343--------------------- 344 345.. function:: void obs_leave_graphics(void) 346 347 Helper function for leaving the OBS graphics context. 348 349--------------------- 350 351.. function:: audio_t *obs_get_audio(void) 352 353 :return: The main audio output handler for this OBS context 354 355--------------------- 356 357.. function:: video_t *obs_get_video(void) 358 359 :return: The main video output handler for this OBS context 360 361--------------------- 362 363.. function:: void obs_set_output_source(uint32_t channel, obs_source_t *source) 364 365 Sets the primary output source for a channel. 366 367--------------------- 368 369.. function:: obs_source_t *obs_get_output_source(uint32_t channel) 370 371 Gets the primary output source for a channel and increments the reference 372 counter for that source. Use :c:func:`obs_source_release()` to release. 373 374--------------------- 375 376.. function:: gs_effect_t *obs_get_base_effect(enum obs_base_effect effect) 377 378 Returns a commoinly used base effect. 379 380 :param effect: | Can be one of the following values: 381 | OBS_EFFECT_DEFAULT - RGB/YUV 382 | OBS_EFFECT_DEFAULT_RECT - RGB/YUV (using texture_rect) 383 | OBS_EFFECT_OPAQUE - RGB/YUV (alpha set to 1.0) 384 | OBS_EFFECT_SOLID - RGB/YUV (solid color only) 385 | OBS_EFFECT_BICUBIC - Bicubic downscale 386 | OBS_EFFECT_LANCZOS - Lanczos downscale 387 | OBS_EFFECT_BILINEAR_LOWRES - Bilinear low resolution downscale 388 | OBS_EFFECT_PREMULTIPLIED_ALPHA - Premultiplied alpha 389 390--------------------- 391 392.. function:: void obs_render_main_view(void) 393 394 Renders the main view. 395 396 Note: This function is deprecated. 397 398--------------------- 399 400.. function:: void obs_render_main_texture(void) 401 402 Renders the main output texture. Useful for rendering a preview pane 403 of the main output. 404 405--------------------- 406 407.. function:: void obs_set_master_volume(float volume) 408 409 Sets the master user volume. 410 411--------------------- 412 413.. function:: float obs_get_master_volume(void) 414 415 :return: The master user volume 416 417--------------------- 418 419.. function:: void obs_enum_audio_monitoring_devices(obs_enum_audio_device_cb cb, void *data) 420 421 Enumerates audio devices which can be used for audio monitoring. 422 423 Relevant data types used with this function: 424 425.. code:: cpp 426 427 typedef bool (*obs_enum_audio_device_cb)(void *data, const char *name, const char *id); 428 429--------------------- 430 431.. function:: bool obs_set_audio_monitoring_device(const char *name, const char *id) 432 433 Sets the current audio device for audio monitoring. 434 435--------------------- 436 437.. function:: void obs_get_audio_monitoring_device(const char **name, const char **id) 438 439 Gets the current audio device for audio monitoring. 440 441--------------------- 442 443.. function:: void obs_add_main_render_callback(void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) 444 void obs_remove_main_render_callback(void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) 445 446 Adds/removes a main rendering callback. Allows custom rendering to 447 the main stream/recording output. 448 449--------------------- 450 451.. function:: void obs_add_raw_video_callback(const struct video_scale_info *conversion, void (*callback)(void *param, struct video_data *frame), void *param) 452 void obs_remove_raw_video_callback(void (*callback)(void *param, struct video_data *frame), void *param) 453 454 Adds/removes a raw video callback. Allows the ability to obtain raw 455 video frames without necessarily using an output. 456 457 :param conversion: Specifies conversion requirements. Can be NULL. 458 :param callback: The callback that receives raw video frames. 459 :param param: The private data associated with the callback. 460 461 462Primary signal/procedure handlers 463--------------------------------- 464 465.. function:: signal_handler_t *obs_get_signal_handler(void) 466 467 :return: The primary obs signal handler 468 469 See :ref:`core_signal_handler_reference` for more information on 470 core signals. 471 472--------------------- 473 474.. function:: proc_handler_t *obs_get_proc_handler(void) 475 476 :return: The primary obs procedure handler 477 478 479.. _core_signal_handler_reference: 480 481Core OBS Signals 482---------------- 483 484**source_create** (ptr source) 485 486 Called when a source has been created. 487 488**source_destroy** (ptr source) 489 490 Called when a source has been destroyed. 491 492**source_remove** (ptr source) 493 494 Called when a source has been removed (:c:func:`obs_source_remove()` 495 has been called on the source). 496 497**source_save** (ptr source) 498 499 Called when a source is being saved. 500 501**source_load** (ptr source) 502 503 Called when a source is being loaded. 504 505**source_activate** (ptr source) 506 507 Called when a source has been activated in the main view (visible on 508 stream/recording). 509 510**source_deactivate** (ptr source) 511 512 Called when a source has been deactivated from the main view (no 513 longer visible on stream/recording). 514 515**source_show** (ptr source) 516 517 Called when a source is visible on any display and/or on the main 518 view. 519 520**source_hide** (ptr source) 521 522 Called when a source is no longer visible on any display and/or on 523 the main view. 524 525**source_rename** (ptr source, string new_name, string prev_name) 526 527 Called when a source has been renamed. 528 529**source_volume** (ptr source, in out float volume) 530 531 Called when a source's volume has changed. 532 533**source_transition_start** (ptr source) 534 535 Called when a transition has started its transition. 536 537**source_transition_video_stop** (ptr source) 538 539 Called when a transition has stopped its video transitioning. 540 541**source_transition_stop** (ptr source) 542 543 Called when a transition has stopped its transition. 544 545**channel_change** (int channel, in out ptr source, ptr prev_source) 546 547 Called when :c:func:`obs_set_output_source()` has been called. 548 549**master_volume** (in out float volume) 550 551 Called when the master volume has changed. 552 553**hotkey_layout_change** () 554 555 Called when the hotkey layout has changed. 556 557**hotkey_register** (ptr hotkey) 558 559 Called when a hotkey has been registered. 560 561**hotkey_unregister** (ptr hotkey) 562 563 Called when a hotkey has been unregistered. 564 565**hotkey_bindings_changed** (ptr hotkey) 566 567 Called when a hotkey's bindings has changed. 568 569--------------------- 570 571 572.. _display_reference: 573 574Displays 575-------- 576 577.. function:: obs_display_t *obs_display_create(const struct gs_init_data *graphics_data) 578 579 Adds a new window display linked to the main render pipeline. This creates 580 a new swap chain which updates every frame. 581 582 *(Important note: do not use more than one display widget within the 583 hierarchy of the same base window; this will cause presentation 584 stalls on Macs.)* 585 586 :param graphics_data: The swap chain initialization data 587 :return: The new display context, or NULL if failed 588 589 Relevant data types used with this function: 590 591.. code:: cpp 592 593 enum gs_color_format { 594 [...] 595 GS_RGBA, 596 GS_BGRX, 597 GS_BGRA, 598 GS_RGBA16F, 599 GS_RGBA32F, 600 [...] 601 }; 602 603 enum gs_zstencil_format { 604 GS_ZS_NONE, 605 GS_Z16, 606 GS_Z24_S8, 607 GS_Z32F, 608 GS_Z32F_S8X24 609 }; 610 611 struct gs_window { 612 #if defined(_WIN32) 613 void *hwnd; 614 #elif defined(__APPLE__) 615 __unsafe_unretained id view; 616 #elif defined(__linux__) || defined(__FreeBSD__) 617 uint32_t id; 618 void *display; 619 #endif 620 }; 621 622 struct gs_init_data { 623 struct gs_window window; 624 uint32_t cx, cy; 625 uint32_t num_backbuffers; 626 enum gs_color_format format; 627 enum gs_zstencil_format zsformat; 628 uint32_t adapter; 629 }; 630 631--------------------- 632 633.. function:: void obs_display_destroy(obs_display_t *display) 634 635 Destroys a display context. 636 637--------------------- 638 639.. function:: void obs_display_resize(obs_display_t *display, uint32_t cx, uint32_t cy) 640 641 Changes the size of a display context. 642 643--------------------- 644 645.. function:: void obs_display_add_draw_callback(obs_display_t *display, void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) 646 647 Adds a draw callback for a display context, which will be called 648 whenever the display is rendered. 649 650 :param display: The display context 651 :param draw: The draw callback which is called each time a frame 652 updates 653 :param param: The user data to be associated with this draw callback 654 655--------------------- 656 657.. function:: void obs_display_remove_draw_callback(obs_display_t *display, void (*draw)(void *param, uint32_t cx, uint32_t cy), void *param) 658 659 Removes a draw callback for a display context. 660 661--------------------- 662 663.. function:: void obs_display_set_enabled(obs_display_t *display, bool enable) 664 665 Enables/disables a display context. 666 667--------------------- 668 669.. function:: bool obs_display_enabled(obs_display_t *display) 670 671 :return: *true* if the display is enabled, *false* otherwise 672 673--------------------- 674 675.. function:: void obs_display_set_background_color(obs_display_t *display, uint32_t color) 676 677 Sets the background (clear) color for the display context. 678