Skip to main content

crabshell_services/audio/
peaks.rs

1//! Peak meters: how loud a sink, a source or an app's stream is now. Each
2//! meter is a record stream the server fills with one peak per channel
3//! [`RATE`] times a second, open only while a config holds the meter.
4
5use std::panic::{self, AssertUnwindSafe, Location};
6use std::rc::Rc;
7use std::sync::Arc;
8
9use calloop::channel::Sender;
10use crabshell_reactive::{ReadSignal, Signal, untrack};
11use crabshell_ui::{IntoProp, Prop};
12use libpulse_binding::channelmap::Map;
13use libpulse_binding::context::{self, Context};
14use libpulse_binding::def::BufferAttr;
15use libpulse_binding::sample::{Format, Spec};
16use libpulse_binding::stream::{FlagSet, PeekResult, State, Stream};
17
18use super::{Audio, AudioService, Event, Locked, Message, Nodes, Pulse, on_pa_thread};
19use crate::dbus::set_changed;
20use crate::lines::panic_message;
21
22/// Peaks a second, as pavucontrol reads them: smooth on a level bar, and
23/// each one wakes the shell, so no more than that.
24const RATE: u32 = 25;
25
26/// What a peak meter listens to, for [`Audio::peaks`].
27#[derive(Clone, Debug, PartialEq, Eq)]
28pub enum PeakTarget {
29  /// The sink called this, through its monitor: what it plays.
30  Sink(String),
31  /// The source called this, such as a microphone or a sink's monitor.
32  Source(String),
33  /// The stream numbered this: what that app plays.
34  Stream(u32),
35}
36
37/// A target that stays.
38impl IntoProp<Option<PeakTarget>> for PeakTarget {
39  fn into_prop(self) -> Prop<Option<PeakTarget>> {
40    // A closure that reads no signal runs once.
41    (move || Some(self.clone())).into_prop()
42  }
43}
44
45impl Audio {
46  /// A peak meter, as Quickshell's `PwNodePeakMonitor`: each channel's
47  /// loudest sample over the last 1/25 s, from 0 to 1, in the order of the
48  /// target's `channels`. Empty while there is no target; all 0 while
49  /// nothing plays.
50  ///
51  /// `target` takes a [`PeakTarget`] or a closure returning an `Option` of
52  /// one; `None` stops the meter. A panic in the closure is logged and stops
53  /// the meter until the next change.
54  ///
55  /// While it records, the shell wakes 25 times a second, but the signal is
56  /// set only when a peak changes. A sink's or stream's meter records only
57  /// while something plays; a source's records all the time. It stops when
58  /// the context that asked goes.
59  #[track_caller]
60  pub fn peaks(&self, target: impl IntoProp<Option<PeakTarget>>) -> ReadSignal<Vec<f32>> {
61    let at = Location::caller();
62    let Some(service) = self.service.clone().filter(|_| !self.owner.is_disposed()) else {
63      return self.no_peaks;
64    };
65    let peaks = self.owner.signal(Vec::new());
66    let target = target.into_prop().shared();
67    // A memo, so a closure that reads a sink's volume moves the meter only
68    // when the target itself changes.
69    let target = self.owner.memo(move || {
70      let chosen = panic::catch_unwind(AssertUnwindSafe(|| target()));
71      chosen.unwrap_or_else(|payload| {
72        let message = panic_message(payload.as_ref());
73        tracing::error!(
74          "cx.audio().peaks (called at {at}) panicked choosing its target: {message}"
75        );
76        None
77      })
78    });
79    // Each run's scope holds the meter it opened, so a new target or the
80    // owner going closes it.
81    self.owner.effect_scoped(move |scope| {
82      if let Some(target) = target.get() {
83        let id = service.meter(target, peaks);
84        scope.signal(Unmeter(Rc::clone(&service), id));
85      }
86    });
87    peaks.read_only()
88  }
89}
90
91/// A meter a config holds: what it listens to, and where its peaks go.
92pub(super) struct Wanted {
93  id: u64,
94  target: PeakTarget,
95  pub(super) peaks: Signal<Vec<f32>>,
96}
97
98/// Closes a meter when the scope that opened it drops this.
99struct Unmeter(Rc<AudioService>, u64);
100
101impl Drop for Unmeter {
102  fn drop(&mut self) {
103    self.0.unmeter(self.1);
104  }
105}
106
107impl AudioService {
108  /// Adds a meter for `target`, recording at once if the server has it.
109  fn meter(&self, target: PeakTarget, peaks: Signal<Vec<f32>>) -> u64 {
110    let id = self.next_meter.get();
111    self.next_meter.set(id + 1);
112    self.meters.borrow_mut().push(Wanted { id, target, peaks });
113    self.sync_meters();
114    id
115  }
116
117  fn unmeter(&self, id: u64) {
118    self.meters.borrow_mut().retain(|meter| meter.id != id);
119    self.sync_meters();
120  }
121
122  /// Opens and closes record streams to match the meters. Untracked: a
123  /// meter's effect calls this, and must not come to depend on the peaks
124  /// it sets.
125  fn sync_meters(&self) {
126    untrack(|| {
127      let wanted = self.meters.borrow();
128      if let Some(pulse) = self.pulse.borrow_mut().as_mut() {
129        pulse.sync_meters(&wanted);
130      }
131    });
132  }
133}
134
135/// Where a meter records from.
136#[derive(Clone, PartialEq)]
137pub(super) struct Source {
138  /// The source's name, a sink's monitor for a sink or a stream.
139  name: String,
140  map: Map,
141  /// The stream to keep to, of those its sink plays.
142  stream: Option<u32>,
143  /// Records only while something else keeps the sink playing, so a
144  /// meter alone never wakes a device. A source's meter isn't: a
145  /// microphone's level shows with nothing else recording.
146  passive: bool,
147}
148
149impl Nodes {
150  /// Where a meter for `target` records from, as last read, and whether
151  /// it is quiet: its sink idle or its stream paused, which sends nothing,
152  /// so the last peaks would stay. `None` while the server doesn't have
153  /// the target.
154  fn source_of(&self, target: &PeakTarget) -> Option<(Source, bool)> {
155    let (name, map, stream, quiet) = match target {
156      PeakTarget::Sink(name) => {
157        let sink = self.sinks.iter().find(|sink| sink.name == *name)?;
158        (sink.monitor_source.clone()?, sink.map, None, !sink.running)
159      }
160      PeakTarget::Source(name) => {
161        let source = self.sources.iter().find(|source| source.name == *name)?;
162        (source.name.clone(), source.map, None, false)
163      }
164      PeakTarget::Stream(index) => {
165        let stream = self.streams.iter().find(|stream| stream.index == *index)?;
166        let sink = self.sinks.iter().find(|sink| sink.index == stream.sink)?;
167        let quiet = stream.corked || !sink.running;
168        let name = sink.monitor_source.clone()?;
169        (name, stream.map, Some(*index), quiet)
170      }
171    };
172    let passive = !matches!(target, PeakTarget::Source(_));
173    let source = Source {
174      name,
175      map,
176      stream,
177      passive,
178    };
179    Some((source, quiet))
180  }
181}
182
183/// A meter's record stream.
184pub(super) struct Meter {
185  id: u64,
186  peaks: Signal<Vec<f32>>,
187  source: Source,
188  /// `None` once the server ended it, or if it didn't open. Either way it
189  /// isn't tried again until its source changes.
190  stream: Option<Recording>,
191  /// While quiet, its peaks are 0, its stream is corked and what it
192  /// still reads is dropped.
193  quiet: bool,
194  /// Whether its stream is corked, as last asked of the server.
195  corked: bool,
196}
197
198impl Meter {
199  /// Corks the stream while quiet, so even a server that sends an idle
200  /// sink's silence sends nothing, and uncorks it after. A stream the
201  /// server is still making is corked once it is made.
202  fn cork(&mut self) {
203    let Some(Recording(stream)) = self.stream.as_mut() else {
204      return;
205    };
206    // libpulse makes no operation for a stream that isn't ready, and the
207    // binding panics on that.
208    if self.corked != self.quiet && stream.get_state() == State::Ready {
209      drop(stream.set_corked_state(self.quiet, None));
210      self.corked = self.quiet;
211    }
212  }
213}
214
215/// A record stream whose callbacks are cleared before it drops: libpulse
216/// calls them again as a stream ends, and from its context while the
217/// server is still making one. Dropped under the mainloop's lock, or with
218/// libpulse's thread stopped.
219pub(super) struct Recording(Stream);
220
221impl Drop for Recording {
222  fn drop(&mut self) {
223    self.0.set_read_callback(None);
224    self.0.set_state_callback(None);
225  }
226}
227
228/// Ends `recording`, under the mainloop's lock. Dropping one disconnects
229/// it, but libpulse refuses that while the server is still making it, and
230/// the server would then record with nothing reading. So that one waits
231/// in `closing` until the server answers.
232fn end(
233  mut recording: Recording,
234  closing: &mut Vec<Recording>,
235  sender: &Arc<Sender<Message>>,
236  generation: u32,
237) {
238  if recording.0.get_state() != State::Creating {
239    return;
240  }
241  recording.0.set_read_callback(None);
242  let sender = Arc::clone(sender);
243  let on_state = on_pa_thread(move || {
244    let _ = sender.send((generation, Event::Closing));
245  });
246  recording.0.set_state_callback(Some(Box::new(on_state)));
247  closing.push(recording);
248}
249
250impl Pulse {
251  /// Closes each meter no longer wanted or whose source changed, and
252  /// opens each wanted one the server has.
253  pub(super) fn sync_meters(&mut self, wanted: &[Wanted]) {
254    let next: Vec<_> = wanted
255      .iter()
256      .map(|meter| (meter.id, meter.peaks, self.nodes.source_of(&meter.target)))
257      .collect();
258    let _lock = Locked::new(&mut self.mainloop);
259    let (closing, sender, generation) = (&mut self.closing, &self.sender, self.generation);
260    self.meters.retain_mut(|meter| {
261      let same = |(id, _, found): &(u64, _, Option<(Source, bool)>)| {
262        *id == meter.id
263          && found
264            .as_ref()
265            .is_some_and(|(source, _)| *source == meter.source)
266      };
267      let kept = next.iter().any(same);
268      if !kept {
269        if let Some(recording) = meter.stream.take() {
270          end(recording, closing, sender, generation);
271        }
272        set_changed(meter.peaks, Vec::new());
273      }
274      kept
275    });
276    let mut context = self.context.as_mut();
277    let ready = context
278      .as_ref()
279      .is_some_and(|c| c.get_state() == context::State::Ready);
280    for (id, peaks, found) in next {
281      let Some((source, quiet)) = found else {
282        continue;
283      };
284      let meter = match self.meters.iter_mut().find(|meter| meter.id == id) {
285        Some(meter) => meter,
286        None => match context.as_mut().filter(|_| ready) {
287          Some(context) => {
288            let stream = open(context, &source, id, &self.sender, self.generation, quiet);
289            self.meters.push(Meter {
290              id,
291              peaks,
292              source,
293              stream,
294              quiet,
295              corked: quiet,
296            });
297            self.meters.last_mut().expect("the meter just pushed")
298          }
299          None => continue,
300        },
301      };
302      meter.quiet = quiet;
303      meter.cork();
304      if quiet && meter.stream.is_some() {
305        let channels = usize::from(meter.source.map.len());
306        set_changed(meter.peaks, vec![0.0; channels]);
307      }
308    }
309  }
310
311  /// Shows the peaks meter `id`'s stream has read since the last time:
312  /// for each channel, the loudest.
313  pub(super) fn read_peaks(&mut self, id: u64) {
314    let _lock = Locked::new(&mut self.mainloop);
315    let Some(meter) = self.meters.iter_mut().find(|meter| meter.id == id) else {
316      return;
317    };
318    let channels = usize::from(meter.source.map.len());
319    let Some(Recording(stream)) = meter.stream.as_mut() else {
320      return;
321    };
322    let mut peaks = None;
323    loop {
324      match stream.peek() {
325        Ok(PeekResult::Data(bytes)) => louder(peaks.get_or_insert(vec![0.0; channels]), bytes),
326        Ok(PeekResult::Hole(_)) => {}
327        Ok(PeekResult::Empty) | Err(_) => break,
328      }
329      if stream.discard().is_err() {
330        break;
331      }
332    }
333    // Quiet, a late reading from before would stay.
334    if let Some(peaks) = peaks.filter(|_| !meter.quiet) {
335      set_changed(meter.peaks, peaks);
336    }
337  }
338
339  /// Closes meter `id` if the server ended its stream, as when its source
340  /// goes, and corks or uncorks it once the server made it.
341  pub(super) fn on_meter_state(&mut self, id: u64) {
342    let _lock = Locked::new(&mut self.mainloop);
343    let Some(meter) = self.meters.iter_mut().find(|meter| meter.id == id) else {
344      return;
345    };
346    let state = meter
347      .stream
348      .as_ref()
349      .map(|recording| recording.0.get_state());
350    if matches!(state, Some(State::Failed | State::Terminated)) {
351      let source = &meter.source.name;
352      tracing::info!(source, "the audio server ended a peak meter");
353      meter.stream = None;
354      set_changed(meter.peaks, Vec::new());
355    }
356    meter.cork();
357  }
358
359  /// Ends each closing stream the server has now made or refused.
360  pub(super) fn on_closing(&mut self) {
361    let _lock = Locked::new(&mut self.mainloop);
362    let made = |recording: &Recording| recording.0.get_state() != State::Creating;
363    self.closing.retain(|recording| !made(recording));
364  }
365}
366
367/// Closes every meter as the connection goes, under the mainloop's lock;
368/// the context's streams go with it. Each meter opens again once the next
369/// connection's lists have its source.
370pub(super) fn close_all(meters: &mut Vec<Meter>, closing: &mut Vec<Recording>) {
371  closing.clear();
372  for meter in meters.drain(..) {
373    set_changed(meter.peaks, Vec::new());
374  }
375}
376
377/// Starts recording peaks from `source`, `corked` or not, under the
378/// mainloop's lock. `None`, logged, if the server or libpulse refused.
379fn open(
380  context: &mut Context,
381  source: &Source,
382  id: u64,
383  sender: &Arc<Sender<Message>>,
384  generation: u32,
385  corked: bool,
386) -> Option<Recording> {
387  let spec = Spec {
388    format: Format::FLOAT32NE,
389    rate: RATE,
390    channels: source.map.len(),
391  };
392  let name = &source.name;
393  let Some(mut stream) = Stream::new(context, "Peak meter", &spec, Some(&source.map)) else {
394    tracing::warn!(name, "libpulse made no stream for a peak meter");
395    return None;
396  };
397  if let Some(index) = source.stream
398    && let Err(error) = stream.set_monitor_stream(index)
399  {
400    tracing::warn!(name, index, %error, "a peak meter couldn't keep to its stream");
401    return None;
402  }
403  // One frame a fragment, so each peak arrives as it is measured.
404  let frame = u32::from(spec.channels) * 4;
405  let attr = BufferAttr {
406    maxlength: u32::MAX,
407    tlength: u32::MAX,
408    prebuf: u32::MAX,
409    minreq: u32::MAX,
410    fragsize: frame,
411  };
412  let mut flags = FlagSet::PEAK_DETECT | FlagSet::ADJUST_LATENCY | FlagSet::DONT_MOVE;
413  if corked {
414    flags |= FlagSet::START_CORKED;
415  }
416  if source.passive {
417    flags |= FlagSet::DONT_INHIBIT_AUTO_SUSPEND;
418  }
419  if let Err(error) = stream.connect_record(Some(name), Some(&attr), flags) {
420    tracing::warn!(name, %error, "the audio server refused a peak meter");
421    return None;
422  }
423  // Set under the lock, so neither runs before the stream is kept.
424  let read = Arc::clone(sender);
425  let on_read = on_pa_thread(move |_| {
426    let _ = read.send((generation, Event::Peaks(id)));
427  });
428  stream.set_read_callback(Some(Box::new(on_read)));
429  let state = Arc::clone(sender);
430  let on_state = on_pa_thread(move || {
431    let _ = state.send((generation, Event::MeterState(id)));
432  });
433  stream.set_state_callback(Some(Box::new(on_state)));
434  Some(Recording(stream))
435}
436
437/// Raises each channel's peak to the loudest sample of the frames of
438/// 32-bit floats in `bytes`, at most 1. A sample that isn't a number
439/// counts as silence.
440pub(super) fn louder(peaks: &mut [f32], bytes: &[u8]) {
441  if peaks.is_empty() {
442    return;
443  }
444  for frame in bytes.chunks_exact(4 * peaks.len()) {
445    for (peak, sample) in peaks.iter_mut().zip(frame.as_chunks::<4>().0) {
446      // `max` passes over NaN.
447      *peak = peak.max(f32::from_ne_bytes(*sample).abs()).min(1.0);
448    }
449  }
450}