Skip to main content

libobs_wrapper/
hotkeys.rs

1//! Managed libobs hotkey registration and binding persistence.
2//!
3//! Native hotkey callbacks never run application code directly. They publish a small owned event
4//! into the wrapper's bounded signal hub; applications consume events from a [`SignalReceiver`]
5//! on their own thread and may then start/stop outputs, save replay buffers, etc. This keeps native
6//! callback work bounded and avoids re-entering blocking wrapper APIs from an OBS callback.
7
8use std::{
9    ffi::{c_void, CStr, CString},
10    sync::Arc,
11};
12
13use crate::{
14    context::ObsContext,
15    data::{object::ObsObjectTrait, output::ObsOutputTrait},
16    encoders::{audio::ObsAudioEncoder, video::ObsVideoEncoder},
17    run_with_obs,
18    runtime::ObsRuntime,
19    services::ObsServiceRef,
20    signals::{SignalHub, SignalReceiver},
21    sources::ObsSourceTrait,
22    unsafe_send::SmartPointerSendable,
23    utils::{ObsError, ObsString},
24};
25
26// C enums are `i32` in the MSVC bindings and `u32` elsewhere, so normalize the
27// interaction flag values to the `u32` used by `obs_key_combination::modifiers`.
28#[allow(clippy::unnecessary_cast)]
29mod modifier_bits {
30    pub(super) const SHIFT: u32 = libobs::obs_interaction_flags_INTERACT_SHIFT_KEY as u32;
31    pub(super) const CONTROL: u32 = libobs::obs_interaction_flags_INTERACT_CONTROL_KEY as u32;
32    pub(super) const ALT: u32 = libobs::obs_interaction_flags_INTERACT_ALT_KEY as u32;
33    pub(super) const COMMAND: u32 = libobs::obs_interaction_flags_INTERACT_COMMAND_KEY as u32;
34}
35
36bitflags::bitflags! {
37    /// Modifier bits accepted by libobs hotkey injection.
38    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
39    pub struct HotkeyModifiers: u32 {
40        const SHIFT = modifier_bits::SHIFT;
41        const CONTROL = modifier_bits::CONTROL;
42        const ALT = modifier_bits::ALT;
43        const COMMAND = modifier_bits::COMMAND;
44    }
45}
46
47#[derive(Debug, Clone, Copy, PartialEq, Eq)]
48pub struct HotkeyEvent {
49    pub id: usize,
50    pub pressed: bool,
51}
52
53#[derive(Debug, Clone, PartialEq, Eq, Default)]
54pub struct HotkeyBindingSnapshot {
55    /// Each entry is one OBS binding object serialized through `obs_data_get_json`.
56    pub entries_json: Vec<String>,
57}
58
59#[derive(Debug, Clone)]
60enum HotkeyOwner {
61    Frontend,
62    Source {
63        _lease: SmartPointerSendable<*mut libobs::obs_source_t>,
64    },
65    Output {
66        _lease: SmartPointerSendable<*mut libobs::obs_output_t>,
67    },
68    Encoder {
69        _lease: SmartPointerSendable<*mut libobs::obs_encoder_t>,
70    },
71    Service {
72        _lease: SmartPointerSendable<*mut libobs::obs_service_t>,
73    },
74}
75
76/// One registered libobs hotkey. Dropping it unregisters the native hotkey on the OBS actor.
77#[derive(Debug)]
78pub struct ObsHotkeyRegistration {
79    id: usize,
80    runtime: ObsRuntime,
81    owner: HotkeyOwner,
82    hub: Arc<SignalHub<HotkeyEvent>>,
83}
84
85impl ObsHotkeyRegistration {
86    pub fn id(&self) -> usize {
87        self.id
88    }
89
90    /// Subscribes to bounded press/release events. Slow subscribers drop new events rather than
91    /// blocking libobs's hotkey callback.
92    pub fn events(&self) -> SignalReceiver<HotkeyEvent> {
93        self.hub.subscribe()
94    }
95
96    /// Saves the native binding array as owned JSON objects suitable for later `load_bindings`.
97    pub fn save_bindings(&self) -> Result<HotkeyBindingSnapshot, ObsError> {
98        let id = self.id;
99        run_with_obs!(self.runtime, move || unsafe {
100            // Safety: id remains registered for the lifetime of `self`; the returned array is
101            // released before leaving the actor command and every item reference is balanced.
102            let array = libobs::obs_hotkey_save(id);
103            if array.is_null() {
104                return Ok(HotkeyBindingSnapshot::default());
105            }
106            let mut entries_json = Vec::with_capacity(libobs::obs_data_array_count(array));
107            for index in 0..libobs::obs_data_array_count(array) {
108                let item = libobs::obs_data_array_item(array, index);
109                if item.is_null() {
110                    continue;
111                }
112                let json = libobs::obs_data_get_json(item);
113                if !json.is_null() {
114                    entries_json.push(CStr::from_ptr(json).to_string_lossy().into_owned());
115                }
116                libobs::obs_data_release(item);
117            }
118            libobs::obs_data_array_release(array);
119            Ok(HotkeyBindingSnapshot { entries_json })
120        })?
121    }
122
123    /// Replaces the native bindings for this registration from a prior snapshot.
124    pub fn load_bindings(&self, snapshot: &HotkeyBindingSnapshot) -> Result<(), ObsError> {
125        let id = self.id;
126        let entries = snapshot
127            .entries_json
128            .iter()
129            .map(|json| CString::new(json.as_str()).map_err(|_| ObsError::JsonParseError))
130            .collect::<Result<Vec<_>, _>>()?;
131        run_with_obs!(self.runtime, (entries), move || unsafe {
132            // Safety: all temporary data/array objects are created, consumed and released on the
133            // OBS actor. `obs_data_array_push_back` increments each item's reference.
134            let array = libobs::obs_data_array_create();
135            if array.is_null() {
136                return Err(ObsError::NullPointer(Some(
137                    "failed to allocate OBS hotkey binding array".into(),
138                )));
139            }
140            for json in &entries {
141                let item = libobs::obs_data_create_from_json(json.as_ptr());
142                if item.is_null() {
143                    libobs::obs_data_array_release(array);
144                    return Err(ObsError::JsonParseError);
145                }
146                libobs::obs_data_array_push_back(array, item);
147                libobs::obs_data_release(item);
148            }
149            libobs::obs_hotkey_load(id, array);
150            libobs::obs_data_array_release(array);
151            Ok(())
152        })?
153    }
154}
155
156#[allow(unknown_lints)]
157#[allow(ensure_obs_call_in_runtime)]
158impl Drop for ObsHotkeyRegistration {
159    fn drop(&mut self) {
160        let id = self.id;
161        let owner = self.owner.clone();
162        let hub = self.hub.clone();
163        self.runtime.defer_obs_cleanup(move || unsafe {
164            // Safety: callback userdata and any object owner lease remain alive through native
165            // unregistration. Dropping them only after unregister prevents callback-after-free.
166            libobs::obs_hotkey_unregister(id);
167            drop(owner);
168            drop(hub);
169        });
170    }
171}
172
173/// # Safety
174/// libobs must call this only while the corresponding registration is alive. `data` must be the
175/// `Arc::as_ptr` value for the `SignalHub` retained through native hotkey unregistration.
176unsafe extern "C" fn hotkey_handler(
177    data: *mut c_void,
178    id: libobs::obs_hotkey_id,
179    _hotkey: *mut libobs::obs_hotkey_t,
180    pressed: bool,
181) {
182    let Some(hub) = (data as *const SignalHub<HotkeyEvent>).as_ref() else {
183        return;
184    };
185    hub.publish(HotkeyEvent { id, pressed });
186}
187
188fn finish_registration(
189    runtime: ObsRuntime,
190    owner: HotkeyOwner,
191    hub: Arc<SignalHub<HotkeyEvent>>,
192    id: usize,
193) -> Result<ObsHotkeyRegistration, ObsError> {
194    if id == usize::MAX {
195        return Err(ObsError::InvalidOperation(
196            "libobs rejected hotkey registration".into(),
197        ));
198    }
199    Ok(ObsHotkeyRegistration {
200        id,
201        runtime,
202        owner,
203        hub,
204    })
205}
206
207fn names(name: &str, description: &str) -> (ObsString, ObsString) {
208    (ObsString::new(name), ObsString::new(description))
209}
210
211pub trait ObsContextHotkeyExt {
212    fn register_frontend_hotkey(
213        &self,
214        name: &str,
215        description: &str,
216    ) -> Result<ObsHotkeyRegistration, ObsError>;
217
218    /// Injects one libobs hotkey press/release event by OBS key name (for example
219    /// `"OBS_KEY_F9"`). This is useful for application-level testing and virtual input; it does
220    /// not synthesize an OS keyboard event.
221    fn inject_hotkey_event(
222        &self,
223        key_name: &str,
224        modifiers: HotkeyModifiers,
225        pressed: bool,
226    ) -> Result<(), ObsError>;
227}
228
229impl ObsContextHotkeyExt for ObsContext {
230    fn register_frontend_hotkey(
231        &self,
232        name: &str,
233        description: &str,
234    ) -> Result<ObsHotkeyRegistration, ObsError> {
235        let (name, description) = names(name, description);
236        let hub = Arc::new(SignalHub::new());
237        let callback_hub = hub.clone();
238        let runtime = self.runtime().clone();
239        let id = run_with_obs!(runtime, (name, description, callback_hub), move || unsafe {
240            // SAFETY: strings and callback state are retained for the actor call and registration.
241            libobs::obs_hotkey_register_frontend(
242                name.as_ptr().0,
243                description.as_ptr().0,
244                Some(hotkey_handler),
245                Arc::as_ptr(&callback_hub) as *mut c_void,
246            )
247        })?;
248        finish_registration(runtime, HotkeyOwner::Frontend, hub, id)
249    }
250
251    fn inject_hotkey_event(
252        &self,
253        key_name: &str,
254        modifiers: HotkeyModifiers,
255        pressed: bool,
256    ) -> Result<(), ObsError> {
257        let key_name = ObsString::new(key_name);
258        let runtime = self.runtime().clone();
259        run_with_obs!(runtime, (key_name), move || unsafe {
260            // Safety: key_name is retained for the actor call; the combination is a plain value.
261            let key = libobs::obs_key_from_name(key_name.as_ptr().0);
262            if key == libobs::obs_key_OBS_KEY_NONE {
263                return Err(ObsError::InvalidOperation(format!(
264                    "unknown OBS hotkey name '{}'",
265                    key_name
266                )));
267            }
268            libobs::obs_hotkey_inject_event(
269                libobs::obs_key_combination_t {
270                    modifiers: modifiers.bits(),
271                    key,
272                },
273                pressed,
274            );
275            Ok(())
276        })?
277    }
278}
279
280pub trait ObsSourceHotkeyExt: ObsSourceTrait {
281    fn register_hotkey(
282        &self,
283        name: &str,
284        description: &str,
285    ) -> Result<ObsHotkeyRegistration, ObsError> {
286        let (name, description) = names(name, description);
287        let hub = Arc::new(SignalHub::new());
288        let callback_hub = hub.clone();
289        let source = self.__native_handle();
290        let source_for_actor = source.clone();
291        let runtime = self.runtime().clone();
292        let id = run_with_obs!(
293            runtime,
294            (source_for_actor, name, description, callback_hub),
295            move || unsafe {
296                // SAFETY: owner lease, strings, and callback state are retained through registration.
297                libobs::obs_hotkey_register_source(
298                    source_for_actor.get_ptr(),
299                    name.as_ptr().0,
300                    description.as_ptr().0,
301                    Some(hotkey_handler),
302                    Arc::as_ptr(&callback_hub) as *mut c_void,
303                )
304            }
305        )?;
306        finish_registration(runtime, HotkeyOwner::Source { _lease: source }, hub, id)
307    }
308}
309impl<T: ObsSourceTrait + ?Sized> ObsSourceHotkeyExt for T {}
310
311pub trait ObsOutputHotkeyExt: ObsOutputTrait {
312    fn register_hotkey(
313        &self,
314        name: &str,
315        description: &str,
316    ) -> Result<ObsHotkeyRegistration, ObsError> {
317        let (name, description) = names(name, description);
318        let hub = Arc::new(SignalHub::new());
319        let callback_hub = hub.clone();
320        let output = self.__native_handle();
321        let output_for_actor = output.clone();
322        let runtime = self.runtime().clone();
323        let id = run_with_obs!(
324            runtime,
325            (output_for_actor, name, description, callback_hub),
326            move || unsafe {
327                // SAFETY: owner lease, strings, and callback state are retained through registration.
328                libobs::obs_hotkey_register_output(
329                    output_for_actor.get_ptr(),
330                    name.as_ptr().0,
331                    description.as_ptr().0,
332                    Some(hotkey_handler),
333                    Arc::as_ptr(&callback_hub) as *mut c_void,
334                )
335            }
336        )?;
337        finish_registration(runtime, HotkeyOwner::Output { _lease: output }, hub, id)
338    }
339}
340impl<T: ObsOutputTrait + ?Sized> ObsOutputHotkeyExt for T {}
341
342pub trait ObsEncoderHotkeyExt: ObsObjectTrait<Native = *mut libobs::obs_encoder_t> {
343    fn register_hotkey(
344        &self,
345        name: &str,
346        description: &str,
347    ) -> Result<ObsHotkeyRegistration, ObsError> {
348        let (name, description) = names(name, description);
349        let hub = Arc::new(SignalHub::new());
350        let callback_hub = hub.clone();
351        let encoder = self.__native_handle();
352        let encoder_for_actor = encoder.clone();
353        let runtime = self.runtime().clone();
354        let id = run_with_obs!(
355            runtime,
356            (encoder_for_actor, name, description, callback_hub),
357            move || unsafe {
358                // SAFETY: owner lease, strings, and callback state are retained through registration.
359                libobs::obs_hotkey_register_encoder(
360                    encoder_for_actor.get_ptr(),
361                    name.as_ptr().0,
362                    description.as_ptr().0,
363                    Some(hotkey_handler),
364                    Arc::as_ptr(&callback_hub) as *mut c_void,
365                )
366            }
367        )?;
368        finish_registration(runtime, HotkeyOwner::Encoder { _lease: encoder }, hub, id)
369    }
370}
371impl ObsEncoderHotkeyExt for ObsAudioEncoder {}
372impl ObsEncoderHotkeyExt for ObsVideoEncoder {}
373
374pub trait ObsServiceHotkeyExt {
375    fn register_hotkey(
376        &self,
377        name: &str,
378        description: &str,
379    ) -> Result<ObsHotkeyRegistration, ObsError>;
380}
381
382impl ObsServiceHotkeyExt for ObsServiceRef {
383    fn register_hotkey(
384        &self,
385        name: &str,
386        description: &str,
387    ) -> Result<ObsHotkeyRegistration, ObsError> {
388        let (name, description) = names(name, description);
389        let hub = Arc::new(SignalHub::new());
390        let callback_hub = hub.clone();
391        let service = self.__native_handle();
392        let service_for_actor = service.clone();
393        let runtime = self.runtime().clone();
394        let id = run_with_obs!(
395            runtime,
396            (service_for_actor, name, description, callback_hub),
397            move || unsafe {
398                // SAFETY: owner lease, strings, and callback state are retained through registration.
399                libobs::obs_hotkey_register_service(
400                    service_for_actor.get_ptr(),
401                    name.as_ptr().0,
402                    description.as_ptr().0,
403                    Some(hotkey_handler),
404                    Arc::as_ptr(&callback_hub) as *mut c_void,
405                )
406            }
407        )?;
408        finish_registration(runtime, HotkeyOwner::Service { _lease: service }, hub, id)
409    }
410}
411
412#[cfg(test)]
413mod tests {
414    use super::*;
415
416    #[test]
417    fn binding_snapshot_is_owned_and_roundtrippable_without_runtime() {
418        let snapshot = HotkeyBindingSnapshot {
419            entries_json: vec![r#"{"key":"OBS_KEY_F9"}"#.into()],
420        };
421        let cloned = snapshot.clone();
422        assert_eq!(snapshot, cloned);
423    }
424}