Skip to main content

libobs_wrapper\sources/
audio.rs

1//! Typed source-level audio controls and managed meter/fader lifetimes.
2
3use std::{ffi::c_void, sync::Arc};
4
5use crate::{
6    data::audio::{AudioMixMask, AudioSyncOffset, LinearVolume},
7    run_with_obs,
8    runtime::ObsRuntime,
9    signals::{SignalHub, SignalReceiver},
10    sources::ObsSourceTrait,
11    unsafe_send::{Sendable, SmartPointerSendable},
12    utils::ObsError,
13};
14
15/// Decibel value used by managed OBS faders.
16///
17/// Negative infinity represents silence. NaN and positive infinity are rejected.
18#[derive(Clone, Copy, Debug, PartialEq)]
19pub struct Decibels(f32);
20
21impl Decibels {
22    pub fn new(db: f32) -> Result<Self, ObsError> {
23        if db.is_nan() || db == f32::INFINITY {
24            return Err(ObsError::InvalidOperation(format!(
25                "decibel value must be finite or negative infinity, got {db}"
26            )));
27        }
28        Ok(Self(db))
29    }
30
31    pub const fn value(self) -> f32 {
32        self.0
33    }
34}
35
36/// OBS fader mapping used for GUI deflection and meter conversion.
37#[derive(Clone, Copy, Debug, PartialEq, Eq)]
38pub enum ObsFaderScale {
39    Cubic,
40    Iec,
41    Logarithmic,
42}
43
44impl ObsFaderScale {
45    fn native(self) -> libobs::obs_fader_type {
46        match self {
47            Self::Cubic => libobs::obs_fader_type_OBS_FADER_CUBIC,
48            Self::Iec => libobs::obs_fader_type_OBS_FADER_IEC,
49            Self::Logarithmic => libobs::obs_fader_type_OBS_FADER_LOG,
50        }
51    }
52}
53
54/// Peak measurement strategy for a managed volume meter.
55#[derive(Clone, Copy, Debug, PartialEq, Eq)]
56pub enum ObsPeakMeterType {
57    SamplePeak,
58    TruePeak,
59}
60
61impl ObsPeakMeterType {
62    fn native(self) -> libobs::obs_peak_meter_type {
63        match self {
64            Self::SamplePeak => libobs::obs_peak_meter_type_SAMPLE_PEAK_METER,
65            Self::TruePeak => libobs::obs_peak_meter_type_TRUE_PEAK_METER,
66        }
67    }
68}
69
70/// How a source is routed to the selected OBS monitoring device.
71#[derive(Clone, Copy, Debug, PartialEq, Eq)]
72pub enum AudioMonitoringType {
73    None,
74    MonitorOnly,
75    MonitorAndOutput,
76}
77
78impl AudioMonitoringType {
79    fn native(self) -> libobs::obs_monitoring_type {
80        match self {
81            Self::None => libobs::obs_monitoring_type_OBS_MONITORING_TYPE_NONE,
82            Self::MonitorOnly => libobs::obs_monitoring_type_OBS_MONITORING_TYPE_MONITOR_ONLY,
83            Self::MonitorAndOutput => {
84                libobs::obs_monitoring_type_OBS_MONITORING_TYPE_MONITOR_AND_OUTPUT
85            }
86        }
87    }
88
89    fn from_native(value: libobs::obs_monitoring_type) -> Result<Self, ObsError> {
90        match value {
91            libobs::obs_monitoring_type_OBS_MONITORING_TYPE_NONE => Ok(Self::None),
92            libobs::obs_monitoring_type_OBS_MONITORING_TYPE_MONITOR_ONLY => Ok(Self::MonitorOnly),
93            libobs::obs_monitoring_type_OBS_MONITORING_TYPE_MONITOR_AND_OUTPUT => {
94                Ok(Self::MonitorAndOutput)
95            }
96            other => Err(ObsError::EnumConversionError(format!(
97                "unknown OBS monitoring type {other}"
98            ))),
99        }
100    }
101}
102
103fn ensure_audio_source<T: ObsSourceTrait + ?Sized>(source: &T) -> Result<(), ObsError> {
104    let source_ptr = source.__native_handle();
105    let runtime = source.runtime().clone();
106    let flags = run_with_obs!(runtime, (source_ptr), move || unsafe {
107        // Safety: the managed source handle retains the source for the actor call.
108        libobs::obs_source_get_output_flags(source_ptr.get_ptr())
109    })?;
110    if flags & libobs::OBS_SOURCE_AUDIO == 0 {
111        return Err(ObsError::InvalidOperation(format!(
112            "source '{}' does not expose OBS_SOURCE_AUDIO",
113            source.name()
114        )));
115    }
116    Ok(())
117}
118
119/// Audio controls available on any managed source that exposes `OBS_SOURCE_AUDIO`.
120pub trait ObsSourceAudioExt: ObsSourceTrait {
121    fn set_volume(&self, volume: LinearVolume) -> Result<(), ObsError> {
122        ensure_audio_source(self)?;
123        let source = self.__native_handle();
124        let runtime = self.runtime().clone();
125        run_with_obs!(runtime, (source), move || unsafe {
126            // Safety: source is retained for the actor call; libobs accepts a linear multiplier.
127            libobs::obs_source_set_volume(source.get_ptr(), volume.multiplier());
128        })
129    }
130
131    fn volume(&self) -> Result<LinearVolume, ObsError> {
132        ensure_audio_source(self)?;
133        let source = self.__native_handle();
134        let runtime = self.runtime().clone();
135        let value = run_with_obs!(runtime, (source), move || unsafe {
136            // Safety: source is retained for the actor call.
137            libobs::obs_source_get_volume(source.get_ptr())
138        })?;
139        LinearVolume::new(value)
140    }
141
142    fn set_muted(&self, muted: bool) -> Result<(), ObsError> {
143        ensure_audio_source(self)?;
144        let source = self.__native_handle();
145        let runtime = self.runtime().clone();
146        run_with_obs!(runtime, (source), move || unsafe {
147            // Safety: source is retained for the actor call.
148            libobs::obs_source_set_muted(source.get_ptr(), muted);
149        })
150    }
151
152    fn muted(&self) -> Result<bool, ObsError> {
153        ensure_audio_source(self)?;
154        let source = self.__native_handle();
155        let runtime = self.runtime().clone();
156        run_with_obs!(runtime, (source), move || unsafe {
157            // Safety: source is retained for the actor call.
158            libobs::obs_source_muted(source.get_ptr())
159        })
160    }
161
162    fn set_sync_offset(&self, offset: AudioSyncOffset) -> Result<(), ObsError> {
163        ensure_audio_source(self)?;
164        let source = self.__native_handle();
165        let runtime = self.runtime().clone();
166        run_with_obs!(runtime, (source), move || unsafe {
167            // Safety: source is retained for the actor call. libobs's unit is nanoseconds.
168            libobs::obs_source_set_sync_offset(source.get_ptr(), offset.nanoseconds());
169        })
170    }
171
172    fn sync_offset(&self) -> Result<AudioSyncOffset, ObsError> {
173        ensure_audio_source(self)?;
174        let source = self.__native_handle();
175        let runtime = self.runtime().clone();
176        let value = run_with_obs!(runtime, (source), move || unsafe {
177            // Safety: source is retained for the actor call.
178            libobs::obs_source_get_sync_offset(source.get_ptr())
179        })?;
180        Ok(AudioSyncOffset::from_nanoseconds(value))
181    }
182
183    /// Routes this source to the selected native audio mixes/tracks.
184    fn set_audio_mixes(&self, mixes: AudioMixMask) -> Result<(), ObsError> {
185        ensure_audio_source(self)?;
186        let source = self.__native_handle();
187        let runtime = self.runtime().clone();
188        run_with_obs!(runtime, (source), move || unsafe {
189            // Safety: source is retained and AudioMixMask prevents out-of-range bits.
190            libobs::obs_source_set_audio_mixers(source.get_ptr(), mixes.bits());
191        })
192    }
193
194    fn audio_mixes(&self) -> Result<AudioMixMask, ObsError> {
195        ensure_audio_source(self)?;
196        let source = self.__native_handle();
197        let runtime = self.runtime().clone();
198        let bits = run_with_obs!(runtime, (source), move || unsafe {
199            // Safety: source is retained for the actor call.
200            libobs::obs_source_get_audio_mixers(source.get_ptr())
201        })?;
202        AudioMixMask::from_bits(bits)
203    }
204
205    fn set_monitoring_type(&self, monitoring: AudioMonitoringType) -> Result<(), ObsError> {
206        ensure_audio_source(self)?;
207        let source = self.__native_handle();
208        let runtime = self.runtime().clone();
209        run_with_obs!(runtime, (source), move || unsafe {
210            // Safety: source is retained for the actor call and enum maps to native constants.
211            libobs::obs_source_set_monitoring_type(source.get_ptr(), monitoring.native());
212        })
213    }
214
215    fn monitoring_type(&self) -> Result<AudioMonitoringType, ObsError> {
216        ensure_audio_source(self)?;
217        let source = self.__native_handle();
218        let runtime = self.runtime().clone();
219        let native = run_with_obs!(runtime, (source), move || unsafe {
220            // Safety: source is retained for the actor call.
221            libobs::obs_source_get_monitoring_type(source.get_ptr())
222        })?;
223        AudioMonitoringType::from_native(native)
224    }
225
226    fn create_fader(&self, scale: ObsFaderScale) -> Result<ObsFader, ObsError> {
227        ObsFader::new(self, scale)
228    }
229
230    fn create_volume_meter(
231        &self,
232        scale: ObsFaderScale,
233        peak_type: ObsPeakMeterType,
234    ) -> Result<ObsVolumeMeter, ObsError> {
235        ObsVolumeMeter::new(self, scale, peak_type)
236    }
237}
238
239impl<T: ObsSourceTrait + ?Sized> ObsSourceAudioExt for T {}
240
241extern "C" fn fader_changed_callback(param: *mut c_void, db: f32) {
242    let Some(hub) = (unsafe {
243        // Safety: callback userdata is Arc::as_ptr from ObsFader and survives native removal.
244        (param as *const SignalHub<Decibels>).as_ref()
245    }) else {
246        return;
247    };
248    if let Ok(db) = Decibels::new(db) {
249        hub.publish(db);
250    }
251}
252
253/// Managed OBS fader attached to one source.
254///
255/// Drop removes the native callback before detaching/destroying the fader, and keeps both callback
256/// state and the source lease alive until that actor-thread cleanup completes.
257#[derive(Debug)]
258pub struct ObsFader {
259    runtime: ObsRuntime,
260    fader: Sendable<*mut libobs::obs_fader_t>,
261    _source: SmartPointerSendable<*mut libobs::obs_source_t>,
262    changed: Arc<SignalHub<Decibels>>,
263}
264
265impl ObsFader {
266    fn new<T: ObsSourceTrait + ?Sized>(source: &T, scale: ObsFaderScale) -> Result<Self, ObsError> {
267        ensure_audio_source(source)?;
268        let source_ptr = source.__native_handle();
269        let source_for_actor = source_ptr.clone();
270        let runtime = source.runtime().clone();
271        let changed = Arc::new(SignalHub::new());
272        let callback_state = changed.clone();
273        let fader = run_with_obs!(
274            runtime,
275            (source_for_actor, callback_state),
276            move || unsafe {
277                // Safety: creation/attachment/callback registration are all actor-thread operations.
278                let fader = libobs::obs_fader_create(scale.native());
279                if fader.is_null() {
280                    return Err(ObsError::NullPointer(Some("obs_fader_create".into())));
281                }
282                if !libobs::obs_fader_attach_source(fader, source_for_actor.get_ptr()) {
283                    libobs::obs_fader_destroy(fader);
284                    return Err(ObsError::InvalidOperation(
285                        "failed to attach OBS fader to source".into(),
286                    ));
287                }
288                libobs::obs_fader_add_callback(
289                    fader,
290                    Some(fader_changed_callback),
291                    Arc::as_ptr(&callback_state) as *mut c_void,
292                );
293                Ok(Sendable(fader))
294            }
295        )??;
296
297        Ok(Self {
298            runtime,
299            fader,
300            _source: source_ptr,
301            changed,
302        })
303    }
304
305    pub fn on_changed(&self) -> SignalReceiver<Decibels> {
306        self.changed.subscribe()
307    }
308
309    pub fn set_db(&self, db: Decibels) -> Result<bool, ObsError> {
310        let fader = self.fader.clone();
311        let runtime = self.runtime.clone();
312        run_with_obs!(runtime, (fader), move || unsafe {
313            // Safety: the fader remains owned by self through the actor call.
314            libobs::obs_fader_set_db(fader.get(), db.value())
315        })
316    }
317
318    pub fn db(&self) -> Result<Decibels, ObsError> {
319        let fader = self.fader.clone();
320        let runtime = self.runtime.clone();
321        let db = run_with_obs!(runtime, (fader), move || unsafe {
322            // Safety: the fader remains owned by self through the actor call.
323            libobs::obs_fader_get_db(fader.get())
324        })?;
325        Decibels::new(db)
326    }
327
328    pub fn set_linear(&self, volume: LinearVolume) -> Result<bool, ObsError> {
329        let fader = self.fader.clone();
330        let runtime = self.runtime.clone();
331        run_with_obs!(runtime, (fader), move || unsafe {
332            // Safety: the fader remains owned by self through the actor call.
333            libobs::obs_fader_set_mul(fader.get(), volume.multiplier())
334        })
335    }
336
337    pub fn linear(&self) -> Result<LinearVolume, ObsError> {
338        let fader = self.fader.clone();
339        let runtime = self.runtime.clone();
340        let value = run_with_obs!(runtime, (fader), move || unsafe {
341            // Safety: the fader remains owned by self through the actor call.
342            libobs::obs_fader_get_mul(fader.get())
343        })?;
344        LinearVolume::new(value)
345    }
346}
347
348#[allow(unknown_lints)]
349#[allow(ensure_obs_call_in_runtime)]
350impl Drop for ObsFader {
351    fn drop(&mut self) {
352        let fader = self.fader.clone();
353        let source = self._source.clone();
354        let changed = self.changed.clone();
355        self.runtime.defer_obs_cleanup(move || unsafe {
356            // Safety: all C callback state is retained in this closure until removal finishes.
357            libobs::obs_fader_remove_callback(
358                fader.get(),
359                Some(fader_changed_callback),
360                Arc::as_ptr(&changed) as *mut c_void,
361            );
362            libobs::obs_fader_detach_source(fader.get());
363            libobs::obs_fader_destroy(fader.get());
364            drop(source);
365        });
366    }
367}
368
369/// Owned snapshot from an OBS volume-meter callback.
370#[derive(Clone, Debug, PartialEq)]
371pub struct VolumeMeterFrame {
372    pub magnitude: [f32; libobs::MAX_AUDIO_CHANNELS as usize],
373    pub peak: [f32; libobs::MAX_AUDIO_CHANNELS as usize],
374    pub input_peak: [f32; libobs::MAX_AUDIO_CHANNELS as usize],
375}
376
377extern "C" fn volume_meter_callback(
378    param: *mut c_void,
379    magnitude: *const f32,
380    peak: *const f32,
381    input_peak: *const f32,
382) {
383    let Some(hub) = (unsafe {
384        // Safety: callback userdata is Arc::as_ptr from ObsVolumeMeter and survives removal.
385        (param as *const SignalHub<VolumeMeterFrame>).as_ref()
386    }) else {
387        return;
388    };
389    if magnitude.is_null() || peak.is_null() || input_peak.is_null() {
390        return;
391    }
392
393    const N: usize = libobs::MAX_AUDIO_CHANNELS as usize;
394    let mut frame = VolumeMeterFrame {
395        magnitude: [0.0; N],
396        peak: [0.0; N],
397        input_peak: [0.0; N],
398    };
399    unsafe {
400        // Safety: OBS declares all three callback pointers as float[MAX_AUDIO_CHANNELS].
401        std::ptr::copy_nonoverlapping(magnitude, frame.magnitude.as_mut_ptr(), N);
402        std::ptr::copy_nonoverlapping(peak, frame.peak.as_mut_ptr(), N);
403        std::ptr::copy_nonoverlapping(input_peak, frame.input_peak.as_mut_ptr(), N);
404    }
405    hub.publish(frame);
406}
407
408/// Managed OBS volume meter attached to one source.
409#[derive(Debug)]
410pub struct ObsVolumeMeter {
411    runtime: ObsRuntime,
412    meter: Sendable<*mut libobs::obs_volmeter_t>,
413    _source: SmartPointerSendable<*mut libobs::obs_source_t>,
414    updates: Arc<SignalHub<VolumeMeterFrame>>,
415    channels: usize,
416}
417
418impl ObsVolumeMeter {
419    fn new<T: ObsSourceTrait + ?Sized>(
420        source: &T,
421        scale: ObsFaderScale,
422        peak_type: ObsPeakMeterType,
423    ) -> Result<Self, ObsError> {
424        ensure_audio_source(source)?;
425        let source_ptr = source.__native_handle();
426        let source_for_actor = source_ptr.clone();
427        let runtime = source.runtime().clone();
428        let updates = Arc::new(SignalHub::new());
429        let callback_state = updates.clone();
430        let (meter, channels) = run_with_obs!(
431            runtime,
432            (source_for_actor, callback_state),
433            move || unsafe {
434                // Safety: creation/attachment/callback registration are actor-thread operations.
435                let meter = libobs::obs_volmeter_create(scale.native());
436                if meter.is_null() {
437                    return Err(ObsError::NullPointer(Some("obs_volmeter_create".into())));
438                }
439                libobs::obs_volmeter_set_peak_meter_type(meter, peak_type.native());
440                if !libobs::obs_volmeter_attach_source(meter, source_for_actor.get_ptr()) {
441                    libobs::obs_volmeter_destroy(meter);
442                    return Err(ObsError::InvalidOperation(
443                        "failed to attach OBS volume meter to source".into(),
444                    ));
445                }
446                libobs::obs_volmeter_add_callback(
447                    meter,
448                    Some(volume_meter_callback),
449                    Arc::as_ptr(&callback_state) as *mut c_void,
450                );
451                let channels = libobs::obs_volmeter_get_nr_channels(meter).max(0) as usize;
452                Ok((
453                    Sendable(meter),
454                    channels.min(libobs::MAX_AUDIO_CHANNELS as usize),
455                ))
456            }
457        )??;
458
459        Ok(Self {
460            runtime,
461            meter,
462            _source: source_ptr,
463            updates,
464            channels,
465        })
466    }
467
468    pub fn channel_count(&self) -> usize {
469        self.channels
470    }
471
472    pub fn on_update(&self) -> SignalReceiver<VolumeMeterFrame> {
473        self.updates.subscribe()
474    }
475}
476
477#[allow(unknown_lints)]
478#[allow(ensure_obs_call_in_runtime)]
479impl Drop for ObsVolumeMeter {
480    fn drop(&mut self) {
481        let meter = self.meter.clone();
482        let source = self._source.clone();
483        let updates = self.updates.clone();
484        self.runtime.defer_obs_cleanup(move || unsafe {
485            // Safety: callback userdata and source lease live through native deregistration.
486            libobs::obs_volmeter_remove_callback(
487                meter.get(),
488                Some(volume_meter_callback),
489                Arc::as_ptr(&updates) as *mut c_void,
490            );
491            libobs::obs_volmeter_detach_source(meter.get());
492            libobs::obs_volmeter_destroy(meter.get());
493            drop(source);
494        });
495    }
496}
497
498#[cfg(test)]
499mod tests {
500    use super::*;
501
502    #[test]
503    fn monitoring_enum_rejects_unknown_native_values() {
504        assert_eq!(
505            AudioMonitoringType::from_native(
506                libobs::obs_monitoring_type_OBS_MONITORING_TYPE_MONITOR_ONLY
507            )
508            .unwrap(),
509            AudioMonitoringType::MonitorOnly
510        );
511        // C enums are `i32` in the MSVC bindings and `u32` elsewhere.
512        #[allow(clippy::unnecessary_cast)]
513        let invalid = u32::MAX as libobs::obs_monitoring_type;
514        assert!(AudioMonitoringType::from_native(invalid).is_err());
515    }
516
517    #[test]
518    fn decibels_accept_silence_but_reject_invalid_values() {
519        assert_eq!(
520            Decibels::new(f32::NEG_INFINITY).unwrap().value(),
521            f32::NEG_INFINITY
522        );
523        assert!(Decibels::new(f32::NAN).is_err());
524        assert!(Decibels::new(f32::INFINITY).is_err());
525    }
526}