libobs_wrapper/lib.rs
1//! Safe, runtime-affine Rust access to the libobs object model.
2//!
3//! # Start here
4//!
5//! [`crate::context::ObsContext`] is the root managed handle. Most applications create it through
6//! [`crate::utils::StartupInfo`], then use only the modules needed for their workflow.
7//!
8//! | What you need | Module |
9//! | --- | --- |
10//! | Discover installed sources/encoders/outputs/services | [`crate::capabilities`] |
11//! | Configure arbitrary plugins from runtime metadata | [`crate::settings`] |
12//! | Sources and filters | [`crate::sources`] |
13//! | Scenes, groups, native order and transform snapshots | [`crate::scenes`] |
14//! | Audio/video encoders | [`crate::encoders`] |
15//! | Streaming services | [`crate::services`] |
16//! | Validated output graphs and lifecycle | [`crate::data::output`] |
17//! | Preview/display surfaces | [`crate::display`] |
18//! | OBS event subscriptions | [`crate::signals`] and per-object `signals()` methods |
19//! | Raw FFI escape hatch | [`crate::sys`] |
20//!
21//! If you only need a conventional recorder, RTMP stream, replay buffer, or common capture source,
22//! the `libobs-simple` crate is normally a better starting point. It uses this wrapper internally
23//! and can be mixed with wrapper calls on the same [`crate::context::ObsContext`].
24//!
25//! # Plugin-generic workflow
26//!
27//! Do not assume every machine has the same OBS plugins. The preferred generic path is:
28//!
29//! 1. call [`crate::context::ObsContext::capabilities`];
30//! 2. choose by codec/protocol/capability, or use
31//! [`crate::capabilities::ObsCapabilities::best_output_plan`];
32//! 3. use descriptor `settings_schema_for` / `settings_snapshot_for` methods to configure plugin
33//! settings without hard-coded property models;
34//! 4. create managed objects from the descriptors;
35//! 5. use [`crate::data::output::ObsOutputPipelineBuilder`] for complete output graphs.
36//!
37//! # Scene composition
38//!
39//! [`crate::scenes::ObsSceneRef`] owns managed scene items and exposes libobs's actual native order.
40//! [`crate::scenes::SceneItemTrait`] covers transform/state behavior, including crop, bounds, scale
41//! filters, blending, and restorable snapshots. [`crate::scenes::ObsSceneGroupRef`] represents native
42//! OBS groups rather than simulating groups in Rust.
43//!
44//! One important libobs behavior is exposed explicitly: ungrouping creates replacement parent-scene
45//! items. [`crate::scenes::ObsSceneGroupRef::ungroup`] therefore returns replacement managed handles
46//! and marks the replaced child handles removed.
47//!
48//! # Ownership and unsafe access
49//!
50//! Managed objects retain native references through one OBS runtime. Clones share a lifetime lease,
51//! and operations validate runtime affinity before combining objects. Prefer opaque object IDs for
52//! identity. [`crate::sys`] is available when raw libobs functionality is genuinely needed, but raw
53//! pointers carry the usual libobs thread-affinity and reference-count responsibilities.
54//!
55//! The repository's `docs/api_orientation.md` contains a longer task-to-module guide and examples.
56
57#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
58
59pub mod capabilities;
60pub mod context;
61pub mod crash_handler;
62pub mod data;
63pub mod display;
64pub mod encoders;
65pub mod enums;
66pub mod logger;
67pub mod runtime;
68pub mod scenes;
69pub mod services;
70pub mod settings;
71pub mod signals;
72pub mod sources;
73#[doc(hidden)]
74pub mod unsafe_send;
75pub mod utils;
76
77pub use libobs as sys;
78
79// Add the macros module to the public exports
80pub mod graphics;
81#[cfg_attr(coverage_nightly, coverage(off))]
82mod macros;