Skip to main content

qualia_audio/
capture.rs

1//! Capture adapter — permission + session (platform device behind desktop).
2//!
3//! Product rule: capture cannot start without explicit intent. Native mic hardware
4//! is injected by the shell (`set_live_pcm`); this module owns the policy gate and
5//! ring state so libraries stay free of WASAPI/cpal types.
6
7use crate::types::AudioError;
8
9/// Visible capture purpose (shown to user before arming).
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum CapturePurpose {
12    Analysis = 1,
13    LanguageDocumentation = 2,
14    Music = 3,
15    Accessibility = 4,
16}
17
18/// Session state — cold construction; pull path is lock-free enough for tests.
19#[derive(Debug, Clone)]
20pub struct CaptureSession {
21    pub purpose: CapturePurpose,
22    pub intent_granted: bool,
23    pub sample_rate: u32,
24    pub channels: u16,
25    /// Ring of mono f32 samples (fixed capacity).
26    ring: Vec<f32>,
27    write: usize,
28    read: usize,
29    pub frames_captured: u64,
30    pub live: bool,
31}
32
33impl CaptureSession {
34    pub const RING_CAP: usize = 48_000 * 2; // ~2s @ 48k
35
36    /// Creates a new instance.
37    pub fn new(purpose: CapturePurpose, sample_rate: u32, channels: u16) -> Self {
38        Self {
39            purpose,
40            intent_granted: false,
41            sample_rate: sample_rate.max(8_000),
42            channels: channels.max(1),
43            ring: vec![0.0; Self::RING_CAP],
44            write: 0,
45            read: 0,
46            frames_captured: 0,
47            live: false,
48        }
49    }
50
51    /// User/shell grants capture for this purpose (Webizen intent).
52    pub fn grant_intent(&mut self) {
53        self.intent_granted = true;
54    }
55
56    /// Revokes intent.
57    pub fn revoke_intent(&mut self) {
58        self.intent_granted = false;
59        self.live = false;
60    }
61
62    /// Arm capture. Fails closed without intent.
63    pub fn start(&mut self) -> Result<(), AudioError> {
64        if !self.intent_granted {
65            return Err(AudioError::PermissionDenied);
66        }
67        self.live = true;
68        Ok(())
69    }
70
71    /// Stops.
72    pub fn stop(&mut self) {
73        self.live = false;
74    }
75
76    /// Shell pushes mono PCM (device or file stream). Dropped if not live.
77    pub fn push_mono(&mut self, samples: &[f32]) -> usize {
78        if !self.live || !self.intent_granted {
79            return 0;
80        }
81        let mut n = 0usize;
82        for &s in samples {
83            let next = (self.write + 1) % self.ring.len();
84            if next == self.read {
85                // overrun: drop oldest
86                self.read = (self.read + 1) % self.ring.len();
87            }
88            self.ring[self.write] = s;
89            self.write = next;
90            n += 1;
91            self.frames_captured += 1;
92        }
93        n
94    }
95
96    /// Pull mono samples into `out`. Returns frames written.
97    pub fn pull_mono(&mut self, out: &mut [f32]) -> usize {
98        let mut n = 0usize;
99        while n < out.len() && self.read != self.write {
100            out[n] = self.ring[self.read];
101            self.read = (self.read + 1) % self.ring.len();
102            n += 1;
103        }
104        n
105    }
106
107    /// `true` when available.
108    pub fn available(&self) -> usize {
109        if self.write >= self.read {
110            self.write - self.read
111        } else {
112            self.ring.len() - self.read + self.write
113        }
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120
121    #[test]
122    fn deny_without_intent() {
123        let mut s = CaptureSession::new(CapturePurpose::Analysis, 16000, 1);
124        assert!(s.start().is_err());
125    }
126
127    #[test]
128    fn grant_push_pull() {
129        let mut s = CaptureSession::new(CapturePurpose::Analysis, 16000, 1);
130        s.grant_intent();
131        s.start().unwrap();
132        let src = [0.1f32, 0.2, 0.3];
133        assert_eq!(s.push_mono(&src), 3);
134        let mut out = [0.0f32; 4];
135        assert_eq!(s.pull_mono(&mut out), 3);
136        assert!((out[1] - 0.2).abs() < 1e-6);
137    }
138}