gstreamer_audio/
audio_info.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use std::{fmt, marker::PhantomData, mem, ptr, slice};
4
5use crate::ffi;
6use glib::translate::{
7    IntoGlib, ToGlibPtr, ToGlibPtrMut, from_glib, from_glib_full, from_glib_none,
8};
9use gst::prelude::*;
10
11/// Information describing audio properties. This information can be filled
12/// in from GstCaps with [`from_caps()`][Self::from_caps()].
13///
14/// Use the provided macros to access the info in this structure.
15#[doc(alias = "GstAudioInfo")]
16#[derive(Clone)]
17#[repr(transparent)]
18pub struct AudioInfo(ffi::GstAudioInfo);
19
20impl fmt::Debug for AudioInfo {
21    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
22        f.debug_struct("AudioInfo")
23            .field("format-info", &self.format_info())
24            .field("rate", &self.rate())
25            .field("channels", &self.channels())
26            .field("positions", &self.positions())
27            .field("flags", &self.flags())
28            .field("layout", &self.layout())
29            .finish()
30    }
31}
32
33#[derive(Debug)]
34#[must_use = "The builder must be built to be used"]
35pub struct AudioInfoBuilder<'a> {
36    format: crate::AudioFormat,
37    rate: u32,
38    channels: u32,
39    positions: Option<&'a [crate::AudioChannelPosition]>,
40    flags: Option<crate::AudioFlags>,
41    layout: Option<crate::AudioLayout>,
42}
43
44impl<'a> AudioInfoBuilder<'a> {
45    #[must_use = "The built AudioInfo must be used"]
46    pub fn build(self) -> Result<AudioInfo, glib::error::BoolError> {
47        unsafe {
48            let mut info = mem::MaybeUninit::uninit();
49
50            if let Some(p) = self.positions {
51                if p.len() != self.channels as usize || p.len() > 64 {
52                    return Err(glib::bool_error!("Invalid positions length"));
53                }
54
55                let valid: bool = from_glib(ffi::gst_audio_check_valid_channel_positions(
56                    p.as_ptr() as *mut _,
57                    self.channels as i32,
58                    true.into_glib(),
59                ));
60                if !valid {
61                    return Err(glib::bool_error!("channel positions are invalid"));
62                }
63            }
64
65            let positions_ptr = self
66                .positions
67                .as_ref()
68                .map(|p| p.as_ptr())
69                .unwrap_or(ptr::null());
70
71            ffi::gst_audio_info_set_format(
72                info.as_mut_ptr(),
73                self.format.into_glib(),
74                self.rate as i32,
75                self.channels as i32,
76                positions_ptr as *mut _,
77            );
78
79            let mut info = info.assume_init();
80
81            if info.finfo.is_null() || info.rate <= 0 || info.channels <= 0 {
82                return Err(glib::bool_error!("Failed to build AudioInfo"));
83            }
84
85            if let Some(flags) = self.flags {
86                info.flags = flags.into_glib();
87            }
88
89            if let Some(layout) = self.layout {
90                info.layout = layout.into_glib();
91            }
92
93            Ok(AudioInfo(info))
94        }
95    }
96
97    pub fn positions(self, positions: &'a [crate::AudioChannelPosition]) -> AudioInfoBuilder<'a> {
98        Self {
99            positions: Some(positions),
100            ..self
101        }
102    }
103
104    pub fn positions_if(
105        self,
106        positions: &'a [crate::AudioChannelPosition],
107        predicate: bool,
108    ) -> AudioInfoBuilder<'a> {
109        if predicate {
110            self.positions(positions)
111        } else {
112            self
113        }
114    }
115
116    pub fn positions_if_some(
117        self,
118        positions: Option<&'a [crate::AudioChannelPosition]>,
119    ) -> AudioInfoBuilder<'a> {
120        if let Some(positions) = positions {
121            self.positions(positions)
122        } else {
123            self
124        }
125    }
126
127    pub fn flags(self, flags: crate::AudioFlags) -> Self {
128        Self {
129            flags: Some(flags),
130            ..self
131        }
132    }
133
134    pub fn flags_if(self, flags: crate::AudioFlags, predicate: bool) -> Self {
135        if predicate { self.flags(flags) } else { self }
136    }
137
138    pub fn flags_if_some(self, flags: Option<crate::AudioFlags>) -> Self {
139        if let Some(flags) = flags {
140            self.flags(flags)
141        } else {
142            self
143        }
144    }
145
146    pub fn layout(self, layout: crate::AudioLayout) -> Self {
147        Self {
148            layout: Some(layout),
149            ..self
150        }
151    }
152
153    pub fn layout_if(self, layout: crate::AudioLayout, predicate: bool) -> Self {
154        if predicate { self.layout(layout) } else { self }
155    }
156
157    pub fn layout_if_some(self, layout: Option<crate::AudioLayout>) -> Self {
158        if let Some(layout) = layout {
159            self.layout(layout)
160        } else {
161            self
162        }
163    }
164}
165
166impl AudioInfo {
167    pub fn builder<'a>(
168        format: crate::AudioFormat,
169        rate: u32,
170        channels: u32,
171    ) -> AudioInfoBuilder<'a> {
172        assert_initialized_main_thread!();
173
174        AudioInfoBuilder {
175            format,
176            rate,
177            channels,
178            positions: None,
179            flags: None,
180            layout: None,
181        }
182    }
183
184    pub fn builder_from_info(info: &AudioInfo) -> AudioInfoBuilder<'_> {
185        assert_initialized_main_thread!();
186
187        AudioInfoBuilder {
188            format: info.format(),
189            rate: info.rate(),
190            channels: info.channels(),
191            positions: info.positions(),
192            flags: Some(info.flags()),
193            layout: Some(info.layout()),
194        }
195    }
196
197    #[inline]
198    pub fn is_valid(&self) -> bool {
199        !self.0.finfo.is_null() && self.0.channels > 0 && self.0.rate > 0 && self.0.bpf > 0
200    }
201
202    /// Parse `caps` to generate a [`AudioInfo`][crate::AudioInfo].
203    /// ## `caps`
204    /// a [`gst::Caps`][crate::gst::Caps]
205    ///
206    /// # Returns
207    ///
208    /// A [`AudioInfo`][crate::AudioInfo], or [`None`] if `caps` couldn't be parsed
209    #[doc(alias = "gst_audio_info_from_caps")]
210    pub fn from_caps(caps: &gst::CapsRef) -> Result<Self, glib::error::BoolError> {
211        skip_assert_initialized!();
212
213        unsafe {
214            let mut info = mem::MaybeUninit::uninit();
215            if from_glib(ffi::gst_audio_info_from_caps(
216                info.as_mut_ptr(),
217                caps.as_ptr(),
218            )) {
219                Ok(Self(info.assume_init()))
220            } else {
221                Err(glib::bool_error!("Failed to create AudioInfo from caps"))
222            }
223        }
224    }
225
226    /// Convert the values of `self` into a [`gst::Caps`][crate::gst::Caps].
227    ///
228    /// # Returns
229    ///
230    /// the new [`gst::Caps`][crate::gst::Caps] containing the
231    ///  info of `self`.
232    #[doc(alias = "gst_audio_info_to_caps")]
233    pub fn to_caps(&self) -> Result<gst::Caps, glib::error::BoolError> {
234        unsafe {
235            let result = from_glib_full(ffi::gst_audio_info_to_caps(&self.0));
236            match result {
237                Some(c) => Ok(c),
238                None => Err(glib::bool_error!("Failed to create caps from AudioInfo")),
239            }
240        }
241    }
242
243    /// Converts among various [`gst::Format`][crate::gst::Format] types. This function handles
244    /// GST_FORMAT_BYTES, GST_FORMAT_TIME, and GST_FORMAT_DEFAULT. For
245    /// raw audio, GST_FORMAT_DEFAULT corresponds to audio frames. This
246    /// function can be used to handle pad queries of the type GST_QUERY_CONVERT.
247    /// ## `src_fmt`
248    /// [`gst::Format`][crate::gst::Format] of the `src_val`
249    /// ## `src_val`
250    /// value to convert
251    /// ## `dest_fmt`
252    /// [`gst::Format`][crate::gst::Format] of the `dest_val`
253    ///
254    /// # Returns
255    ///
256    /// TRUE if the conversion was successful.
257    ///
258    /// ## `dest_val`
259    /// pointer to destination value
260    #[doc(alias = "gst_audio_info_convert")]
261    pub fn convert<U: gst::format::SpecificFormattedValueFullRange>(
262        &self,
263        src_val: impl gst::format::FormattedValue,
264    ) -> Option<U> {
265        assert_initialized_main_thread!();
266        unsafe {
267            let mut dest_val = mem::MaybeUninit::uninit();
268            if from_glib(ffi::gst_audio_info_convert(
269                &self.0,
270                src_val.format().into_glib(),
271                src_val.into_raw_value(),
272                U::default_format().into_glib(),
273                dest_val.as_mut_ptr(),
274            )) {
275                Some(U::from_raw(U::default_format(), dest_val.assume_init()))
276            } else {
277                None
278            }
279        }
280    }
281
282    pub fn convert_generic(
283        &self,
284        src_val: impl gst::format::FormattedValue,
285        dest_fmt: gst::Format,
286    ) -> Option<gst::GenericFormattedValue> {
287        assert_initialized_main_thread!();
288        unsafe {
289            let mut dest_val = mem::MaybeUninit::uninit();
290            if from_glib(ffi::gst_audio_info_convert(
291                &self.0,
292                src_val.format().into_glib(),
293                src_val.into_raw_value(),
294                dest_fmt.into_glib(),
295                dest_val.as_mut_ptr(),
296            )) {
297                Some(gst::GenericFormattedValue::new(
298                    dest_fmt,
299                    dest_val.assume_init(),
300                ))
301            } else {
302                None
303            }
304        }
305    }
306
307    #[inline]
308    pub fn format(&self) -> crate::AudioFormat {
309        if self.0.finfo.is_null() {
310            return crate::AudioFormat::Unknown;
311        }
312
313        unsafe { from_glib((*self.0.finfo).format) }
314    }
315
316    #[inline]
317    pub fn format_info(&self) -> crate::AudioFormatInfo {
318        crate::AudioFormatInfo::from_format(self.format())
319    }
320
321    #[inline]
322    pub fn layout(&self) -> crate::AudioLayout {
323        unsafe { from_glib(self.0.layout) }
324    }
325
326    #[inline]
327    pub fn flags(&self) -> crate::AudioFlags {
328        unsafe { from_glib(self.0.flags) }
329    }
330
331    #[inline]
332    pub fn rate(&self) -> u32 {
333        self.0.rate as u32
334    }
335
336    #[inline]
337    pub fn channels(&self) -> u32 {
338        self.0.channels as u32
339    }
340
341    #[inline]
342    pub fn bpf(&self) -> u32 {
343        self.0.bpf as u32
344    }
345
346    #[inline]
347    pub fn bps(&self) -> u32 {
348        self.format_info().depth() >> 3
349    }
350
351    #[inline]
352    pub fn depth(&self) -> u32 {
353        self.format_info().depth()
354    }
355
356    #[inline]
357    pub fn width(&self) -> u32 {
358        self.format_info().width()
359    }
360
361    #[inline]
362    pub fn endianness(&self) -> crate::AudioEndianness {
363        self.format_info().endianness()
364    }
365
366    #[inline]
367    pub fn is_big_endian(&self) -> bool {
368        self.format_info().is_big_endian()
369    }
370
371    #[inline]
372    pub fn is_little_endian(&self) -> bool {
373        self.format_info().is_little_endian()
374    }
375
376    #[inline]
377    pub fn is_float(&self) -> bool {
378        self.format_info().is_float()
379    }
380
381    #[inline]
382    pub fn is_integer(&self) -> bool {
383        self.format_info().is_integer()
384    }
385
386    #[inline]
387    pub fn is_signed(&self) -> bool {
388        self.format_info().is_signed()
389    }
390
391    #[inline]
392    pub fn positions(&self) -> Option<&[crate::AudioChannelPosition]> {
393        if self.0.channels > 64 || self.is_unpositioned() {
394            return None;
395        }
396
397        Some(unsafe {
398            slice::from_raw_parts(
399                &self.0.position as *const i32 as *const crate::AudioChannelPosition,
400                self.0.channels as usize,
401            )
402        })
403    }
404
405    #[inline]
406    pub fn is_unpositioned(&self) -> bool {
407        self.flags().contains(crate::AudioFlags::UNPOSITIONED)
408    }
409}
410
411impl PartialEq for AudioInfo {
412    #[doc(alias = "gst_audio_info_is_equal")]
413    #[inline]
414    fn eq(&self, other: &Self) -> bool {
415        unsafe { from_glib(ffi::gst_audio_info_is_equal(&self.0, &other.0)) }
416    }
417}
418
419impl Eq for AudioInfo {}
420
421unsafe impl Send for AudioInfo {}
422unsafe impl Sync for AudioInfo {}
423
424impl glib::types::StaticType for AudioInfo {
425    #[inline]
426    fn static_type() -> glib::types::Type {
427        unsafe { glib::translate::from_glib(ffi::gst_audio_info_get_type()) }
428    }
429}
430
431impl glib::value::ValueType for AudioInfo {
432    type Type = Self;
433}
434
435#[doc(hidden)]
436unsafe impl<'a> glib::value::FromValue<'a> for AudioInfo {
437    type Checker = glib::value::GenericValueTypeOrNoneChecker<Self>;
438
439    unsafe fn from_value(value: &'a glib::Value) -> Self {
440        unsafe {
441            skip_assert_initialized!();
442            from_glib_none(glib::gobject_ffi::g_value_get_boxed(value.to_glib_none().0)
443                as *mut ffi::GstAudioInfo)
444        }
445    }
446}
447
448#[doc(hidden)]
449impl glib::value::ToValue for AudioInfo {
450    fn to_value(&self) -> glib::Value {
451        let mut value = glib::Value::for_value_type::<Self>();
452        unsafe {
453            glib::gobject_ffi::g_value_set_boxed(
454                value.to_glib_none_mut().0,
455                self.to_glib_none().0 as *mut _,
456            )
457        }
458        value
459    }
460
461    fn value_type(&self) -> glib::Type {
462        Self::static_type()
463    }
464}
465
466#[doc(hidden)]
467impl From<AudioInfo> for glib::Value {
468    fn from(v: AudioInfo) -> glib::Value {
469        skip_assert_initialized!();
470        glib::value::ToValue::to_value(&v)
471    }
472}
473
474#[doc(hidden)]
475impl glib::value::ToValueOptional for AudioInfo {
476    fn to_value_optional(s: Option<&Self>) -> glib::Value {
477        skip_assert_initialized!();
478        let mut value = glib::Value::for_value_type::<Self>();
479        unsafe {
480            glib::gobject_ffi::g_value_set_boxed(
481                value.to_glib_none_mut().0,
482                s.to_glib_none().0 as *mut _,
483            )
484        }
485        value
486    }
487}
488
489#[doc(hidden)]
490impl glib::translate::Uninitialized for AudioInfo {
491    #[inline]
492    unsafe fn uninitialized() -> Self {
493        unsafe { mem::zeroed() }
494    }
495}
496
497#[doc(hidden)]
498impl glib::translate::GlibPtrDefault for AudioInfo {
499    type GlibType = *mut ffi::GstAudioInfo;
500}
501
502#[doc(hidden)]
503impl<'a> glib::translate::ToGlibPtr<'a, *const ffi::GstAudioInfo> for AudioInfo {
504    type Storage = PhantomData<&'a Self>;
505
506    #[inline]
507    fn to_glib_none(&'a self) -> glib::translate::Stash<'a, *const ffi::GstAudioInfo, Self> {
508        glib::translate::Stash(&self.0, PhantomData)
509    }
510
511    fn to_glib_full(&self) -> *const ffi::GstAudioInfo {
512        unimplemented!()
513    }
514}
515
516#[doc(hidden)]
517impl glib::translate::FromGlibPtrNone<*const ffi::GstAudioInfo> for AudioInfo {
518    #[inline]
519    unsafe fn from_glib_none(ptr: *const ffi::GstAudioInfo) -> Self {
520        unsafe { Self(ptr::read(ptr)) }
521    }
522}
523
524#[doc(hidden)]
525impl glib::translate::FromGlibPtrNone<*mut ffi::GstAudioInfo> for AudioInfo {
526    #[inline]
527    unsafe fn from_glib_none(ptr: *mut ffi::GstAudioInfo) -> Self {
528        unsafe { Self(ptr::read(ptr)) }
529    }
530}
531
532#[doc(hidden)]
533impl glib::translate::FromGlibPtrFull<*mut ffi::GstAudioInfo> for AudioInfo {
534    #[inline]
535    unsafe fn from_glib_full(ptr: *mut ffi::GstAudioInfo) -> Self {
536        unsafe {
537            let info = from_glib_none(ptr);
538            glib::ffi::g_free(ptr as *mut _);
539            info
540        }
541    }
542}
543
544#[cfg(test)]
545mod tests {
546    use super::*;
547
548    #[test]
549    fn test_new() {
550        gst::init().unwrap();
551
552        let info = AudioInfo::builder(crate::AudioFormat::S16le, 48000, 2)
553            .build()
554            .unwrap();
555        assert_eq!(info.format(), crate::AudioFormat::S16le);
556        assert_eq!(info.rate(), 48000);
557        assert_eq!(info.channels(), 2);
558        assert_eq!(
559            &info.positions().unwrap(),
560            &[
561                crate::AudioChannelPosition::FrontLeft,
562                crate::AudioChannelPosition::FrontRight,
563            ]
564        );
565
566        let positions = [
567            crate::AudioChannelPosition::RearLeft,
568            crate::AudioChannelPosition::RearRight,
569        ];
570        let info = AudioInfo::builder(crate::AudioFormat::S16le, 48000, 2)
571            .positions(&positions)
572            .build()
573            .unwrap();
574        assert_eq!(info.format(), crate::AudioFormat::S16le);
575        assert_eq!(info.rate(), 48000);
576        assert_eq!(info.channels(), 2);
577        assert_eq!(
578            &info.positions().unwrap(),
579            &[
580                crate::AudioChannelPosition::RearLeft,
581                crate::AudioChannelPosition::RearRight,
582            ]
583        );
584    }
585
586    #[test]
587    fn test_from_to_caps() {
588        gst::init().unwrap();
589
590        let caps = crate::AudioCapsBuilder::new_interleaved()
591            .format(crate::AudioFormat::S16le)
592            .rate(48000)
593            .channels(2)
594            .fallback_channel_mask()
595            .build();
596        let info = AudioInfo::from_caps(&caps).unwrap();
597        assert_eq!(info.format(), crate::AudioFormat::S16le);
598        assert_eq!(info.rate(), 48000);
599        assert_eq!(info.channels(), 2);
600        assert_eq!(
601            &info.positions().unwrap(),
602            &[
603                crate::AudioChannelPosition::FrontLeft,
604                crate::AudioChannelPosition::FrontRight,
605            ]
606        );
607
608        let caps2 = info.to_caps().unwrap();
609        assert_eq!(caps, caps2);
610
611        let info2 = AudioInfo::from_caps(&caps2).unwrap();
612        assert!(info == info2);
613    }
614}
gstreamer_audio/audio_info.rs

gstreamer_audio/
audio_info.rs
