klingt 0.3.3

Lock-free audio graph library with message-passing parameter control
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

//! CPAL device discovery and sink creation.
//!
//! This module provides [`CpalDevice`] for discovering and selecting audio output devices.
//!
//! # Example: List and Select a Device
//!
//! ```no_run
//! use klingt::{Klingt, CpalDevice};
//!
//! // List all available output devices
//! let devices = CpalDevice::list_outputs();
//! for (i, device) in devices.iter().enumerate() {
//!     println!("[{}] {} ({} Hz, {} ch)",
//!         i, device.name(), device.sample_rate(), device.channels());
//! }
//!
//! // Use a specific device
//! let device = &devices[0];
//! let mut klingt = Klingt::new(device.sample_rate())
//!     .with_output(device.create_sink());
//! ```

use alloc::string::String;
use alloc::vec::Vec;

#[cfg(feature = "cpal_sink")]
use cpal::traits::{DeviceTrait, HostTrait};

/// A discovered audio output device.
///
/// Use [`CpalDevice::default_output`] to get the system default, or
/// [`CpalDevice::list_outputs`] to enumerate all available devices.
///
/// Once you have a device, use [`create_sink`](Self::create_sink) to create
/// a [`CpalSink`](crate::nodes::CpalSink) node for audio output.
pub struct CpalDevice {
    #[cfg(feature = "cpal_sink")]
    device: cpal::Device,
    #[cfg(feature = "cpal_sink")]
    config: cpal::SupportedStreamConfig,
    
    name: String,
    sample_rate: u32,
    channels: u16,
}

impl CpalDevice {
    /// Get the system's default output device.
    ///
    /// Returns `None` if no audio device is available.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use klingt::CpalDevice;
    /// if let Some(device) = CpalDevice::default_output() {
    ///     println!("Default: {} at {} Hz", device.name(), device.sample_rate());
    /// }
    /// ```
    #[cfg(feature = "cpal_sink")]
    pub fn default_output() -> Option<Self> {
        let host = cpal::default_host();
        let device = host.default_output_device()?;
        let config = device.default_output_config().ok()?;
        let name = device.name().unwrap_or_else(|_| "Unknown".into());
        
        Some(Self {
            sample_rate: config.sample_rate().0,
            channels: config.channels(),
            name,
            device,
            config,
        })
    }
    
    #[cfg(not(feature = "cpal_sink"))]
    pub fn default_output() -> Option<Self> {
        None
    }
    
    /// List all available audio output devices.
    ///
    /// Returns an empty list if no devices are found or if enumeration fails.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use klingt::CpalDevice;
    /// for device in CpalDevice::list_outputs() {
    ///     println!("{}: {} Hz", device.name(), device.sample_rate());
    /// }
    /// ```
    #[cfg(feature = "cpal_sink")]
    pub fn list_outputs() -> Vec<Self> {
        let host = cpal::default_host();
        host.output_devices()
            .map(|devices| {
                devices.filter_map(|device| {
                    let config = device.default_output_config().ok()?;
                    let name = device.name().unwrap_or_else(|_| "Unknown".into());
                    Some(Self {
                        sample_rate: config.sample_rate().0,
                        channels: config.channels(),
                        name,
                        device,
                        config,
                    })
                }).collect()
            })
            .unwrap_or_default()
    }
    
    #[cfg(not(feature = "cpal_sink"))]
    pub fn list_outputs() -> Vec<Self> {
        Vec::new()
    }
    
    /// Get the device name.
    pub fn name(&self) -> &str {
        &self.name
    }
    
    /// Get the device's sample rate in Hz.
    pub fn sample_rate(&self) -> u32 {
        self.sample_rate
    }
    
    /// Get the number of output channels.
    pub fn channels(&self) -> u16 {
        self.channels
    }
    
    /// Create a sink node that outputs audio to this device.
    ///
    /// The returned [`CpalSink`](crate::nodes::CpalSink) should be added to
    /// your graph via [`Klingt::with_output`](crate::Klingt::with_output).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use klingt::{Klingt, CpalDevice};
    /// let device = CpalDevice::default_output().unwrap();
    /// let klingt = Klingt::new(device.sample_rate())
    ///     .with_output(device.create_sink());
    /// ```
    #[cfg(feature = "cpal_sink")]
    pub fn create_sink(&self) -> crate::nodes::CpalSink {
        crate::nodes::CpalSink::new(&self.device, &self.config)
    }
}