Merge pull request #23 from nevermore23274/enhance/visualizer-profiler

feat: adjustable visualizer smoothing + profiler improvements (v0.7.4)

Author: nevermore23274

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "AetherTune"
-version = "0.7.3"
+version = "0.7.4"
 edition = "2024"
 
 [dependencies]

docs/PROFILING.md

@@ -8,6 +8,8 @@ Press `` ` `` (backtick) to toggle the profiler overlay. While it's open:
 
 - `>` or `.` — decrease tick rate by 10ms (faster updates, more CPU)
 - `<` or `,` — increase tick rate by 10ms (slower updates, less CPU)
+- `}` — increase smoothing by 5% (smoother bars, more visual lag)
+- `{` — decrease smoothing by 5% (snappier bars, more jitter)
 
 ## Reading the Profiler
 
@@ -67,11 +69,35 @@ These should be well under 100µs each. If IPC poll is consistently high, it may
 | **Idle wait** | Time spent sleeping in `event::poll()`, waiting for input or timeout. This is not CPU work. |
 | **Frame** | Full wall-clock time per loop iteration (work + idle) |
 
+Idle wait and Frame use **inverted color coding**: high values are green (the CPU is mostly sleeping, which is good), low values are red (the app is struggling to find idle time).
+
+### Visualizer Responsiveness
+
+This section shows how quickly the visualizer bars react to changes in the audio signal.
+
+```
+Smoothing     70%  │  { } adjust
+Settling      7 frames  (~70ms @ 10ms tick)
+```
+
+**Smoothing** is the noise reduction weight used in the visualizer's integral smoothing (an exponential moving average). Higher values produce smoother, more flowing bar animation but introduce visual lag. Lower values make bars snap to the audio faster but may look jittery. The default is 70% (CAVA uses 77%). Adjustable in 5% steps with `{` and `}`.
+
+**Settling** is the theoretical number of frames for bars to reach 90% of a new target value, calculated as `⌈ln(0.1) / ln(smoothing)⌉`. The millisecond estimate multiplies this by your current tick rate. Color coding: green under 200ms, yellow under 500ms, red above.
+
+| Smoothing | Settling (frames) | @ 10ms tick | @ 30ms tick | Feel |
+|-----------|-------------------|-------------|-------------|------|
+| 50% | 4 | 40ms | 120ms | Snappy, some jitter |
+| 70% | 7 | 70ms | 210ms | Default — responsive with smooth flow |
+| 85% | 15 | 150ms | 450ms | Very smooth, noticeable lag |
+| 95% | 45 | 450ms | 1350ms | Flowing but sluggish |
+
+The smoothing value is runtime-only and resets to the default (70%) on restart.
+
 ### The avg and max Columns
 
 **avg** is the mean over the rolling window. **max** is the highest value seen in that same window. Both use a 2-second rolling window (~60 frames), so old spikes fall off naturally — you're always seeing recent performance, not a startup spike from minutes ago.
 
-Max values are color-coded: green under 5,000µs, yellow under 10,000µs, red above.
+For CPU work metrics (Draw, Key input, IPC poll, Visualizer, CPU work), values are color-coded where low is green and high is red. For idle metrics (Idle wait, Frame), the coloring is inverted — high values are green because they indicate the CPU is mostly sleeping.
 
 ## Optimizing for Your System
 

src/audio/visualizer.rs

@@ -5,10 +5,10 @@ use crate::audio::pipe::{SharedAnalysis, NUM_BANDS};
 const NUM_BARS: usize = NUM_BANDS; // Match the frequency bands
 const MAX_HEIGHT: u16 = 12;
 
-/// Noise reduction factor (0.0 = fast/noisy, 1.0 = slow/smooth)
+/// Default noise reduction factor (0.0 = fast/noisy, 1.0 = slow/smooth)
 /// Controls both integral smoothing weight and gravity modifier.
 /// CAVA default is 0.77; we use 0.70 for slightly more responsiveness in a TUI.
-const NOISE_REDUCTION: f64 = 0.70;
+const DEFAULT_NOISE_REDUCTION: f64 = 0.70;
 
 /// Gravity acceleration increment per frame when a bar is falling.
 /// CAVA uses 0.028; we match that.
@@ -43,6 +43,9 @@ pub struct Visualizer {
     sensitivity: f64,
     /// Whether we're still in the initial ramp-up phase
     sens_init: bool,
+    /// Noise reduction / smoothing weight (0.0 = instant, 1.0 = frozen)
+    /// Adjustable at runtime via the profiler overlay
+    pub noise_reduction: f64,
 }
 
 impl Visualizer {
@@ -58,6 +61,7 @@ impl Visualizer {
             cava_mem: vec![0.0; NUM_BARS],
             sensitivity: 1.0,
             sens_init: true,
+            noise_reduction: DEFAULT_NOISE_REDUCTION,
         }
     }
 
@@ -83,7 +87,7 @@ impl Visualizer {
         let vol_scale = volume as f64 / 100.0;
 
         // Gravity modifier: higher noise_reduction = lower gravity = slower fall
-        let gravity_mod = 1.0 - (NOISE_REDUCTION * 0.5);
+        let gravity_mod = 1.0 - (self.noise_reduction * 0.5);
 
         let mut overshoot = false;
         let silence = rms < 0.001;
@@ -113,7 +117,7 @@ impl Visualizer {
             // --- Integral smoothing ---
             // Weighted running average: memory accumulates over time,
             // blending the previous memory with the current value
-            out = self.cava_mem[i] * NOISE_REDUCTION + out;
+            out = self.cava_mem[i] * self.noise_reduction + out;
             self.cava_mem[i] = out;
 
             // --- Autosens clamping ---
@@ -158,7 +162,7 @@ impl Visualizer {
 
         if !is_playing {
             // Apply gravity fall-off even in simulated mode for smooth stop
-            let gravity_mod = 1.0 - (NOISE_REDUCTION * 0.5);
+            let gravity_mod = 1.0 - (self.noise_reduction * 0.5);
             for i in 0..NUM_BARS {
                 if self.bars[i] > 0 {
                     self.cava_fall[i] += GRAVITY_STEP;
@@ -183,7 +187,7 @@ impl Visualizer {
         self.active = true;
         let mut rng = rand::rng();
         let vol_scale = volume as f64 / 100.0;
-        let gravity_mod = 1.0 - (NOISE_REDUCTION * 0.5);
+        let gravity_mod = 1.0 - (self.noise_reduction * 0.5);
 
         if self.frame % 3 == 0 {
             let has_real_data = audio_level > 0.01;
@@ -220,7 +224,7 @@ impl Visualizer {
                 self.prev_out[i] = out;
 
                 // Integral smoothing
-                out = self.cava_mem[i] * NOISE_REDUCTION + out;
+                out = self.cava_mem[i] * self.noise_reduction + out;
                 self.cava_mem[i] = out;
 
                 out = out.min(1.0);
@@ -319,7 +323,7 @@ mod tests {
 
     #[test]
     fn test_gravity_constants_are_sane() {
-        assert!(NOISE_REDUCTION > 0.0 && NOISE_REDUCTION < 1.0);
+        assert!(DEFAULT_NOISE_REDUCTION > 0.0 && DEFAULT_NOISE_REDUCTION < 1.0);
         assert!(GRAVITY_STEP > 0.0 && GRAVITY_STEP < 0.1);
         assert!(AUTOSENS_DECREASE < 1.0);
         assert!(AUTOSENS_INCREASE > 1.0);

src/main.rs

@@ -286,6 +286,22 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                         } else if app.show_perf && app.keybindings.perf_tick_faster.matches(kc) {
                             app.tick_rate_ms = app.tick_rate_ms.saturating_sub(10).max(10);
                             app.save_config();
+
+                        // Smoothing adjustment (only when profiler is open)
+                        } else if app.show_perf && kc == KeyCode::Char('{') {
+                            // Decrease smoothing (more responsive)
+                            let nr = app.visualizer.noise_reduction;
+                            app.visualizer.noise_reduction = ((nr - 0.05) * 100.0).round() / 100.0;
+                            if app.visualizer.noise_reduction < 0.05 {
+                                app.visualizer.noise_reduction = 0.05;
+                            }
+                        } else if app.show_perf && kc == KeyCode::Char('}') {
+                            // Increase smoothing (smoother)
+                            let nr = app.visualizer.noise_reduction;
+                            app.visualizer.noise_reduction = ((nr + 0.05) * 100.0).round() / 100.0;
+                            if app.visualizer.noise_reduction > 0.95 {
+                                app.visualizer.noise_reduction = 0.95;
+                            }
                         }
                     }
                     InputMode::Editing => match key.code {

src/ui/perf_overlay.rs

@@ -92,23 +92,69 @@ pub fn draw(f: &mut Frame, app: &App, area: Rect) {
     // Section header
     lines.push(section_header("Per-frame work (all frames)"));
     lines.push(column_header());
-    lines.push(timing_line("Draw", avg.draw_us, max.draw_us));
-    lines.push(timing_line("Key input", avg.event_handle_us, max.event_handle_us));
+    lines.push(timing_line("Draw", avg.draw_us, max.draw_us, false));
+    lines.push(timing_line("Key input", avg.event_handle_us, max.event_handle_us, false));
     lines.push(Line::from(""));
 
     // Tick-only section
     lines.push(section_header("Tick work (tick frames only)"));
     lines.push(column_header());
-    lines.push(timing_line("IPC poll", summary.tick_avg_poll_us, summary.tick_max_poll_us));
-    lines.push(timing_line("Visualizer", summary.tick_avg_vis_us, summary.tick_max_vis_us));
+    lines.push(timing_line("IPC poll", summary.tick_avg_poll_us, summary.tick_max_poll_us, false));
+    lines.push(timing_line("Visualizer", summary.tick_avg_vis_us, summary.tick_max_vis_us, false));
+    lines.push(Line::from(""));
+
+    // Visualizer responsiveness section
+    lines.push(section_header("Visualizer responsiveness"));
+    // Settling frames = ln(0.1) / ln(noise_reduction) — frames for bars to reach 90% of target
+    let noise_reduction = app.visualizer.noise_reduction;
+    let settling_frames = if noise_reduction > 0.0 && noise_reduction < 1.0 {
+        (0.1_f64.ln() / noise_reduction.ln()).ceil() as u64
+    } else {
+        0
+    };
+    let settling_ms = settling_frames * tick_ms;
+    let settling_color = if settling_ms > 200 {
+        RED
+    } else if settling_ms > 100 {
+        YELLOW
+    } else {
+        NEON_GREEN
+    };
+    lines.push(Line::from(vec![
+        Span::styled(
+            format!("  Smoothing     "),
+            Style::default().fg(Color::Rgb(140, 140, 160)),
+        ),
+        Span::styled(
+            format!("{:.0}%", noise_reduction * 100.0),
+            Style::default().fg(CYAN).add_modifier(Modifier::BOLD),
+        ),
+        Span::styled("  │  ", Style::default().fg(Color::Rgb(50, 50, 70))),
+        Span::styled("{ } ", Style::default().fg(Color::Rgb(80, 80, 110))),
+        Span::styled("adjust", Style::default().fg(Color::Rgb(60, 60, 90))),
+    ]));
+    lines.push(Line::from(vec![
+        Span::styled(
+            format!("  Settling      "),
+            Style::default().fg(Color::Rgb(140, 140, 160)),
+        ),
+        Span::styled(
+            format!("{} frames", settling_frames),
+            Style::default().fg(settling_color),
+        ),
+        Span::styled(
+            format!("  (~{}ms @ {}ms tick)", settling_ms, tick_ms),
+            Style::default().fg(Color::Rgb(100, 100, 130)),
+        ),
+    ]));
     lines.push(Line::from(""));
 
     // Totals
     lines.push(section_header("Totals"));
     lines.push(column_header());
-    lines.push(timing_line("CPU work", work_avg, max.work_us()));
-    lines.push(timing_line("Idle wait", avg.event_wait_us, max.event_wait_us));
-    lines.push(timing_line("Frame", avg.total_us, max.total_us));
+    lines.push(timing_line("CPU work", work_avg, max.work_us(), false));
+    lines.push(timing_line("Idle wait", avg.event_wait_us, max.event_wait_us, true));
+    lines.push(timing_line("Frame", avg.total_us, max.total_us, true));
     lines.push(Line::from(""));
 
     lines.push(Line::from(""));
@@ -124,7 +170,7 @@ pub fn draw(f: &mut Frame, app: &App, area: Rect) {
         Span::styled(" >80%", Style::default().fg(Color::Rgb(60, 60, 90))),
     ]));
     lines.push(Line::from(Span::styled(
-        "  ` close  │  < > tick rate  │  2s rolling window",
+        "  ` close  │  < > tick rate  │  { } smoothing  │  2s rolling window",
         Style::default().fg(Color::Rgb(60, 60, 90)),
     )));
 
@@ -157,23 +203,46 @@ fn column_header() -> Line<'static> {
     ))
 }
 
-fn timing_line(label: &str, avg: u64, max: u64) -> Line<'static> {
-    let color = if avg > 5000 {
-        RED
-    } else if avg > 2000 {
-        YELLOW
-    } else if avg > 500 {
-        Color::Rgb(180, 200, 180)
+fn timing_line(label: &str, avg: u64, max: u64, invert: bool) -> Line<'static> {
+    // For inverted rows (idle wait, frame), high values are good (green)
+    // For normal rows (CPU work, draw, etc.), low values are good (green)
+    let color = if invert {
+        // High = good (sleeping a lot), low = bad (busy)
+        if avg < 2000 {
+            RED
+        } else if avg < 5000 {
+            YELLOW
+        } else {
+            NEON_GREEN
+        }
     } else {
-        NEON_GREEN
+        if avg > 5000 {
+            RED
+        } else if avg > 2000 {
+            YELLOW
+        } else if avg > 500 {
+            Color::Rgb(180, 200, 180)
+        } else {
+            NEON_GREEN
+        }
     };
 
-    let max_color = if max > 10000 {
-        RED
-    } else if max > 5000 {
-        YELLOW
+    let max_color = if invert {
+        if max < 2000 {
+            RED
+        } else if max < 5000 {
+            YELLOW
+        } else {
+            Color::Rgb(100, 100, 130)
+        }
     } else {
-        Color::Rgb(100, 100, 130)
+        if max > 10000 {
+            RED
+        } else if max > 5000 {
+            YELLOW
+        } else {
+            Color::Rgb(100, 100, 130)
+        }
     };
 
     Line::from(vec![