docs(audio): add inline comments throughout audio crate

Add concise, high-signal inline comments to function bodies across the
audio processing implementation. Comments explain intent, edge cases,
boundary math, ownership/cloning decisions, and performance trade-offs
rather than restating code behavior.

Key areas covered:
- Audio input (CPAL device handling, sample format conversion, threading)
- EQ pipeline (FFT processing, log-spaced bands, smoothing, normalization)
- VAD gate (hysteresis logic, timing accumulation, state transitions)
- SFX player (oscillator, envelope, double beep sequencing)

Author: hate

keyless-audio/src/eq_pipeline.rs

@@ -58,9 +58,10 @@ pub struct EqState {
 impl EqState {
     /// Create a new state with cached FFT/buffers for the given layout.
     pub fn new(bands: usize, nfft: usize) -> Self {
-        // Initialize FFT planner and plan once
+        // Initialize FFT planner and plan once (expensive operation, cached for reuse).
         let mut planner = RealFftPlanner::<f32>::new();
         let fft_plan = planner.plan_fft_forward(nfft);
+        // Real FFT produces N/2+1 complex bins (second half is mirror image).
         let spectrum_size = fft_plan.complex_len();
 
         let scratch_size = fft_plan.get_scratch_len();
@@ -71,6 +72,7 @@ impl EqState {
             input_buf: vec![0.0; nfft],
             spectrum_buf: vec![Complex32::new(0.0, 0.0); spectrum_size],
             scratch_buf: vec![Complex32::new(0.0, 0.0); scratch_size],
+            // Use with_capacity (not fixed size) since mags_buf length = spectrum_size (varies by FFT).
             mags_buf: Vec::with_capacity(spectrum_size),
             band_mags_buf: vec![0.0; bands],
             bars_buf: vec![0.0; bands],
@@ -82,6 +84,8 @@ impl EqState {
 /// Uses auto-sensitivity (max normalization) for consistent visualization.
 /// All buffers are reused from state for zero allocations.
 pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u16> {
+    // Early return if frame too short: can't fill FFT window, reuse previous smoothed values.
+    // This handles startup/edge cases where buffer hasn't accumulated enough samples yet.
     if frame.len() < cfg.nfft {
         // Not enough samples; keep the current smooth values
         return state
@@ -100,8 +104,11 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
     // Fix: Multiply each sample by a "window" that fades to zero at both ends (bell curve shape).
     // Hann window formula: w[i] = 0.5 - 0.5 * cos(2π * i / N)
     // This gives smooth transitions and cleaner frequency bins.
+    // Take last nfft samples (most recent audio); ensures we analyze latest data.
     let start = frame.len() - cfg.nfft;
     for (i, s) in frame[start..].iter().enumerate() {
+        // Hann window: symmetric bell curve (peaks at center, fades to 0 at edges).
+        // Formula: 0.5 - 0.5*cos(2π*i/N) produces values in [0, 1] range.
         let w = 0.5 - 0.5 * ((2.0 * std::f32::consts::PI * i as f32) / (cfg.nfft as f32)).cos();
         state.input_buf[i] = *s * w;
     }
@@ -113,6 +120,7 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
     //
     // Output: Complex numbers (real + imaginary). Each complex number represents one frequency bin.
     // We only care about the first half because the second half is a mirror (real FFT property).
+    // Input buffer is modified in-place; spectrum_buf receives frequency-domain output.
     let _ = state.fft_plan.process_with_scratch(
         &mut state.input_buf,
         &mut state.spectrum_buf,
@@ -126,9 +134,12 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
     //
     // Analogy: Think of (re, im) as a 2D point. The magnitude is its distance from origin.
     // This gives us a single "loudness" value per frequency bin.
+    // Real FFT produces N/2+1 bins (mirror property); we only need first half for visualization.
     let half = state.spectrum_buf.len();
+    // Clear and reuse mags_buf (with_capacity avoids realloc, clear resets length to 0).
     state.mags_buf.clear();
     for c in &state.spectrum_buf[0..half] {
+        // Magnitude = sqrt(re² + im²); represents amplitude/loudness of this frequency bin.
         state.mags_buf.push((c.re * c.re + c.im * c.im).sqrt());
     }
 
@@ -144,19 +155,27 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
     // Math: f(i) = start_hz * (nyquist / 50)^(i / (bands - 1))
     // This spreads bands from ~120 Hz (low bass) to Nyquist (half the sample rate) on a log scale.
     let nyquist = cfg.sample_rate_hz / 2.0;
+    // Reset band magnitudes to zero before accumulation (reuse buffer).
     state.band_mags_buf.fill(0.0);
     for (i, band_mag) in state.band_mags_buf.iter_mut().enumerate() {
-        // Compute frequency range for this band (exponential growth)
+        // Compute frequency range for this band (exponential growth).
+        // Formula spreads bands logarithmically from start_hz to nyquist.
+        // Division by (bands - 1) ensures last band ends at nyquist (i = bands - 1).
         let f0 = cfg.start_hz * (nyquist / 50.0).powf(i as f32 / (cfg.bands - 1) as f32);
         let f1 = cfg.start_hz * (nyquist / 50.0).powf((i + 1) as f32 / (cfg.bands - 1) as f32);
 
-        // Map frequency range to FFT bin indices
+        // Map frequency range to FFT bin indices (linear mapping: freq → bin).
+        // Clamp to valid bin range [0, half-1] to prevent OOB access.
+        // half-1 because bins are 0-indexed; last valid bin is at index half-1.
         let bin0 = ((f0 / nyquist) * (half as f32 - 1.0)).clamp(0.0, half as f32 - 1.0) as usize;
         let bin1 = ((f1 / nyquist) * (half as f32 - 1.0)).clamp(0.0, half as f32 - 1.0) as usize;
 
-        // Find the loudest frequency in this band
+        // Find the loudest frequency in this band (peak detection, not average).
+        // Max preserves sharp peaks better than averaging (important for visualization).
         let mut max_v = 0.0f32;
+        // Inclusive range bin0..=bin1; max(bin0) handles edge case where bin1 < bin0 (shouldn't happen).
         for b in bin0..=bin1.max(bin0) {
+            // Bounds check: get() returns None if index OOB (defensive).
             if let Some(&m) = state.mags_buf.get(b)
                 && m > max_v
             {
@@ -173,13 +192,15 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
     //
     // Fix: Find the loudest band right now, and normalize all bands relative to that max.
     // This ensures bars fill the screen consistently regardless of absolute volume.
+    // Fold finds maximum magnitude across all bands (O(n) scan).
     let max_mag = state.band_mags_buf.iter().copied().fold(0.0f32, f32::max);
 
     // Step 6: Shape the bars for clean visualization
     for (i, bar) in state.bars_buf.iter_mut().enumerate() {
         let mag = state.band_mags_buf[i];
 
-        // Normalize against the loudest band (0.0 = silence, 1.0 = loudest right now)
+        // Normalize against the loudest band (0.0 = silence, 1.0 = loudest right now).
+        // Check max_mag > 1e-12 to avoid division by zero (silence case).
         let normalized = if max_mag > 1e-12 { mag / max_mag } else { 0.0 };
 
         // Apply noise reduction: filter out low-level background noise
@@ -188,18 +209,24 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
         // the range (threshold..1.0) back to (0..1.0) so the visualizer stays smooth.
         //
         // Example: threshold=0.3, band=0.5 → (0.5 - 0.3) / (1.0 - 0.3) = 0.29 (rescaled)
+        // Rescaling preserves relative differences above threshold while suppressing noise below.
         let filtered = if normalized < cfg.noise_reduction {
             0.0
         } else {
+            // Linear rescale: maps [threshold, 1.0] → [0.0, 1.0].
             (normalized - cfg.noise_reduction) / (1.0 - cfg.noise_reduction)
         };
 
         // Apply perceptual shaping (window_db and gamma curve)
         //
         // window_db: Compresses dynamic range (makes quiet sounds more visible)
         // gamma: Power curve for perceptual brightness (like monitor gamma correction)
+        // Clamp filtered*window_db to [0, window_db] then normalize back to [0, 1].
+        // This effectively applies window_db as a scaling factor.
         let scaled = (filtered * cfg.window_db).min(cfg.window_db) / cfg.window_db;
+        // Gamma curve: pow(scaled, gamma) darkens (gamma>1) or brightens (gamma<1) the visualization.
         let curved = scaled.powf(cfg.gamma);
+        // Convert to 0..100 range for final bar height; clamp prevents overflow.
         *bar = (curved * 100.0).clamp(0.0, 100.0);
     }
 
@@ -216,13 +243,19 @@ pub fn compute_bars(frame: &[f32], cfg: &EqConfig, state: &mut EqState) -> Vec<u
     // Formula: new_value = old_value + α * (target - old_value)
     // α = attack (if rising) or decay (if falling); typical values 0.35 attack, 0.12 decay
     for i in 0..cfg.bands {
+        // Bounds check: get_mut() returns None if index OOB (defensive, shouldn't happen).
         if let Some(s) = state.smooth_bars.get_mut(i) {
+            // Get target bar value; fallback to 0.0 if index OOB (defensive).
             let target = state.bars_buf.get(i).copied().unwrap_or(0.0);
+            // Choose smoothing factor: attack for rising, decay for falling (asymmetric response).
             let alpha = if target > *s { cfg.attack } else { cfg.decay };
+            // Exponential smoothing: move fraction α of the way toward target each frame.
             *s = *s + alpha * (target - *s);
         }
     }
 
+    // Convert smoothed bars to u16 (0..100 range) for final output.
+    // Clamp to [0, 100] to handle any floating-point precision issues or smoothing overshoot.
     state
         .smooth_bars
         .iter()

keyless-audio/src/input/api.rs

@@ -67,12 +67,14 @@ pub fn default_input_name() -> keyless_core::error::KeylessResult<String> {
 pub fn list_input_device_names() -> keyless_core::error::KeylessResult<Vec<String>> {
     let host = cpal::default_host();
     let mut out = Vec::new();
+    // Iterate all input devices; skip devices where name() fails (may be unplugged/permission issue).
     for dev in host.input_devices().map_err(|e| {
         keyless_core::error::KeylessError::Audio(format!(
             "failed to enumerate input devices: {}",
             e
         ))
     })? {
+        // Silently skip devices that can't provide a name (defensive; better than failing entire list).
         if let Ok(name) = dev.name() {
             out.push(name);
         }
@@ -84,6 +86,7 @@ pub fn list_input_device_names() -> keyless_core::error::KeylessResult<Vec<Strin
 pub fn list_input_devices() -> keyless_core::error::KeylessResult<Vec<InputDevice>> {
     let host = cpal::default_host();
     let mut out = Vec::new();
+    // Wrap each device in Arc for shared ownership (allows cloning InputDevice handles).
     for dev in host.input_devices().map_err(|e| {
         keyless_core::error::KeylessError::Audio(format!(
             "failed to enumerate input devices: {}",
@@ -100,9 +103,11 @@ pub fn list_input_devices() -> keyless_core::error::KeylessResult<Vec<InputDevic
 /// Get the system default input device as an opaque handle.
 pub fn default_input_device() -> keyless_core::error::KeylessResult<InputDevice> {
     let host = cpal::default_host();
+    // OS chooses default device (usually the primary microphone or first available).
     let dev = host.default_input_device().ok_or_else(|| {
         keyless_core::error::KeylessError::Audio("no input device available".to_string())
     })?;
+    // Wrap in Arc for shared ownership (allows cloning the handle).
     Ok(InputDevice {
         inner: Arc::new(dev),
     })