audio_visualizer/live/

mod.rs

/*
MIT License

Copyright (c) 2026 Philipp Schuster

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
//! Live audio visualization: records audio from an input device and shows it
//! in a real-time GUI window ([`egui`](https://crates.io/crates/egui)).
//!
//! Start with [`LiveVisualizer`]; see the `live_visualize_*` examples in
//! `examples/`. **Run this only with `--release`, otherwise it is very
//! laggy.**
//!
//! # What the window shows
//!
//! The upper chart is the recorded audio, the lower chart a [`Transform`] of
//! it, e.g. a lowpass-filtered waveform or a frequency spectrum. Both cover
//! the last five seconds and scroll from right (now) to left.
//!
//! Recording is always mono. A stereo device is averaged down to one
//! channel, so a transformation always receives a single sequence of
//! amplitudes, and each chart shows a single signal.
//!
//! A waveform is drawn as a filled shape from the smallest to the largest
//! amplitude per pixel column, not as a line through individual samples: a
//! column covers a few hundred samples at common sample rates. See
//! [`crate::WaveformVisualizer`] for why that is the right thing to show.

mod input;

pub use input::AudioInput;

use crate::Error;
use crate::waveform::{Bucket, envelope_exact};
use eframe::egui;
use eframe::egui::{Color32, Stroke};
use egui_plot::{FilledArea, Line, Plot, PlotPoints};
use input::AudioBuffer;
use std::ops::Range;
use std::sync::{Arc, Mutex};

/// How many seconds of the latest audio are kept and displayed.
const AUDIO_HISTORY_SECONDS: usize = 5;

/// Upper bound of waveform points per chart; roughly one point per
/// horizontal pixel.
const MAX_POINTS: usize = 1600;

/// Color of the recorded audio in the upper chart.
const ORIGINAL_COLOR: Color32 = Color32::from_rgb(0x4a, 0x9e, 0xda);
/// Color of the transformation in the lower chart.
const TRANSFORM_COLOR: Color32 = Color32::from_rgb(0xe8, 0x9c, 0x3a);

/// Closure type of [`Transform::Waveform`].
pub type WaveformFn<'a> = Box<dyn FnMut(&[f32], f32) -> Vec<f32> + 'a>;
/// Closure type of [`Transform::Points`].
pub type PointsFn<'a> = Box<dyn FnMut(&[f32], f32) -> Vec<(f64, f64)> + 'a>;

/// Transformation of the recorded audio, displayed in the lower half of the
/// [`LiveVisualizer`] window.
///
/// Called with the latest audio samples (mono amplitudes in `[-1.0, 1.0]`)
/// and the sample rate in Hz, once per rendered frame. The closures may hold
/// state (`FnMut`), e.g. for smoothing across frames.
#[expect(missing_debug_implementations)]
pub enum Transform<'a> {
    /// The output is a waveform on the same time axis as the input, e.g. a
    /// filtered version of it.
    Waveform(WaveformFn<'a>),
    /// The output is a series of arbitrary `(x, y)` points, e.g. a frequency
    /// spectrum.
    Points(PointsFn<'a>),
}

impl<'a> Transform<'a> {
    /// Creates a [`Transform::Waveform`].
    pub fn waveform(f: impl FnMut(&[f32], f32) -> Vec<f32> + 'a) -> Self {
        Self::Waveform(Box::new(f))
    }

    /// Creates a [`Transform::Points`].
    pub fn points(f: impl FnMut(&[f32], f32) -> Vec<(f64, f64)> + 'a) -> Self {
        Self::Points(Box::new(f))
    }
}

/// Builder that opens a GUI window showing the live waveform of an audio
/// input device along with a custom [`Transform`] of it.
///
/// # Example
/// ```no_run
/// use audio_visualizer::live::{LiveVisualizer, Transform};
///
/// LiveVisualizer::new(Transform::waveform(|samples, _sample_rate| {
///     samples.iter().map(|s| s * 0.5).collect()
/// }))
/// .title("Half amplitude")
/// .open()
/// .unwrap();
/// ```
#[allow(missing_debug_implementations)]
pub struct LiveVisualizer<'a> {
    transform: Transform<'a>,
    title: String,
    input: Option<AudioInput>,
    x_range: Option<Range<f64>>,
    y_range: Option<Range<f64>>,
    x_label: String,
    y_label: String,
    window_size: (f32, f32),
}

impl<'a> LiveVisualizer<'a> {
    /// Creates a live visualizer with the given transformation for the lower
    /// chart.
    #[must_use]
    pub fn new(transform: Transform<'a>) -> Self {
        Self {
            transform,
            title: "Live Audio Visualization".to_string(),
            input: None,
            x_range: None,
            y_range: None,
            x_label: String::new(),
            y_label: String::new(),
            window_size: (1280.0, 720.0),
        }
    }

    /// Sets the window title.
    #[must_use]
    pub fn title(mut self, title: impl Into<String>) -> Self {
        self.title = title.into();
        self
    }

    /// Sets the audio input to record from. Default: the system default
    /// input device.
    #[must_use]
    pub fn input(mut self, input: AudioInput) -> Self {
        self.input = Some(input);
        self
    }

    /// Fixes the x-axis range of the lower chart. Default: the same time
    /// axis as the waveform for [`Transform::Waveform`], automatic bounds
    /// for [`Transform::Points`].
    #[must_use]
    pub const fn x_range(mut self, range: Range<f64>) -> Self {
        self.x_range = Some(range);
        self
    }

    /// Fixes the y-axis range of the lower chart. See [`Self::x_range`].
    #[must_use]
    pub const fn y_range(mut self, range: Range<f64>) -> Self {
        self.y_range = Some(range);
        self
    }

    /// Sets the axis labels of the lower chart.
    #[must_use]
    pub fn axis_labels(mut self, x: impl Into<String>, y: impl Into<String>) -> Self {
        self.x_label = x.into();
        self.y_label = y.into();
        self
    }

    /// Sets the initial window size in logical pixels. Default: 1280x720.
    #[must_use]
    pub const fn window_size(mut self, width: f32, height: f32) -> Self {
        self.window_size = (width, height);
        self
    }

    /// Starts recording, opens the window and blocks until it is closed
    /// (close button or Escape key).
    pub fn open(self) -> Result<(), Error> {
        let input = match self.input {
            Some(input) => input,
            None => AudioInput::default_device()?,
        };
        let sample_rate = input.config().sample_rate as f32;

        let audio = Arc::new(Mutex::new(AudioBuffer::new(
            (AUDIO_HISTORY_SECONDS * sample_rate as usize).next_power_of_two(),
        )));

        let stream = input.build_stream(audio.clone())?;
        cpal::traits::StreamTrait::play(&stream)
            .map_err(|e| Error::Audio(format!("can't start recording: {e}")))?;

        let app = App {
            audio,
            sample_rate,
            transform: self.transform,
            x_range: self.x_range,
            y_range: self.y_range,
            x_label: self.x_label,
            y_label: self.y_label,
        };
        #[allow(clippy::tuple_array_conversions)]
        let options = eframe::NativeOptions {
            viewport: egui::ViewportBuilder::default()
                .with_inner_size([self.window_size.0, self.window_size.1]),
            ..Default::default()
        };
        eframe::run_native(&self.title, options, Box::new(move |_cc| Ok(Box::new(app))))
            .map_err(|e| Error::Gui(e.to_string()))?;

        // dropped here, after the window is closed: recording stops
        drop(stream);
        Ok(())
    }
}

/// The [`eframe`] application: two vertically stacked plots, redrawn
/// continuously with the latest audio data.
struct App<'a> {
    audio: Arc<Mutex<AudioBuffer>>,
    sample_rate: f32,
    transform: Transform<'a>,
    x_range: Option<Range<f64>>,
    y_range: Option<Range<f64>>,
    x_label: String,
    y_label: String,
}

impl eframe::App for App<'_> {
    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        let ctx = ui.ctx().clone();
        if ctx.input(|i| i.key_pressed(egui::Key::Escape)) {
            ctx.send_viewport_cmd(egui::ViewportCommand::Close);
        }

        // lock released immediately; the copy keeps the audio callback fast
        let (samples, total) = self.audio.lock().unwrap().snapshot();
        // The buffer is always full, so this does not change between frames.
        let bucket_len = samples.len().div_ceil(MAX_POINTS);

        egui::Frame::central_panel(ui.style()).show(ui, |ui| {
            let plot_height = ui.available_height() / 2.0 - ui.spacing().item_spacing.y;
            let history_secs = samples.len() as f64 / self.sample_rate as f64;

            fixed_plot("waveform")
                .height(plot_height)
                .x_axis_label("time (seconds)")
                .y_axis_label("amplitude")
                .default_x_bounds(-history_secs, 0.0)
                .default_y_bounds(-1.0, 1.0)
                .show(ui, |plot_ui| {
                    plot_ui.add(waveform_area(
                        "original",
                        &samples,
                        self.sample_rate,
                        total,
                        bucket_len,
                        ORIGINAL_COLOR,
                    ));
                });

            let mut plot = fixed_plot("transformed")
                .height(plot_height)
                .x_axis_label(&self.x_label)
                .y_axis_label(&self.y_label);
            match &mut self.transform {
                Transform::Waveform(f) => {
                    let transformed = f(&samples, self.sample_rate);
                    let (x0, x1) = self
                        .x_range
                        .as_ref()
                        .map_or((-history_secs, 0.0), |r| (r.start, r.end));
                    let (y0, y1) = self
                        .y_range
                        .as_ref()
                        .map_or((-1.0, 1.0), |r| (r.start, r.end));
                    plot = plot.default_x_bounds(x0, x1).default_y_bounds(y0, y1);
                    plot.show(ui, |plot_ui| {
                        plot_ui.add(waveform_area(
                            "transformed",
                            &transformed,
                            self.sample_rate,
                            total,
                            bucket_len,
                            TRANSFORM_COLOR,
                        ));
                    });
                }
                Transform::Points(f) => {
                    let points = f(&samples, self.sample_rate);
                    // an axis without a fixed range keeps automatic bounds
                    if let Some(r) = &self.x_range {
                        plot = plot.default_x_bounds(r.start, r.end);
                    }
                    if let Some(r) = &self.y_range {
                        plot = plot.default_y_bounds(r.start, r.end);
                    }
                    plot.show(ui, |plot_ui| {
                        let points: PlotPoints = points.iter().map(|(x, y)| [*x, *y]).collect();
                        plot_ui.line(Line::new("transformed", points).color(TRANSFORM_COLOR));
                    });
                }
            }
        });

        // continuous rendering, the audio buffer changes permanently
        ctx.request_repaint();
    }
}

/// A plot with a fixed view: the live data moves, the cursor must not.
fn fixed_plot<'p>(id: &str) -> Plot<'p> {
    Plot::new(id)
        .allow_drag(false)
        .allow_zoom(false)
        .allow_scroll(false)
        .allow_boxed_zoom(false)
        .allow_double_click_reset(false)
        .allow_axis_zoom_drag(false)
}

/// The waveform as one filled shape between the per-bucket minimum and
/// maximum, with x as seconds relative to now (`-history..0`).
///
/// The min/max envelope describes a single signal, so it is drawn as a
/// single item in a single color. Two separate lines would read as two
/// unrelated signals.
///
/// `samples` are the newest `samples.len()` of the `total` samples recorded
/// so far; a transformation may return fewer, which then covers accordingly
/// less time.
fn waveform_area(
    name: &str,
    samples: &[f32],
    sample_rate: f32,
    total: u64,
    bucket_len: usize,
    color: Color32,
) -> FilledArea {
    let (anchor, buckets) = aligned_envelope(samples, total, bucket_len);
    let time_of =
        |offset: usize| ((anchor + offset as u64) as f64 - total as f64) / sample_rate as f64;

    let xs: Vec<f64> = buckets.iter().map(|b| time_of(b.start)).collect();
    let mins: Vec<f64> = buckets.iter().map(|b| b.min as f64).collect();
    let maxs: Vec<f64> = buckets.iter().map(|b| b.max as f64).collect();

    FilledArea::new(name, &xs, &mins, &maxs)
        .fill_color(color.gamma_multiply(0.45))
        .stroke(Stroke::new(1.0, color))
}

/// Reduces `samples` to min/max buckets that are aligned to absolute
/// positions in the audio stream, and returns the stream position of the
/// first bucket along with them.
///
/// # Invariant
///
/// Bucket boundaries sit on multiples of `bucket_len` counted from the start
/// of the stream, never relative to `samples[0]`. A given stretch of audio
/// therefore always lands in the same bucket and keeps its min/max until it
/// scrolls out of the window.
///
/// This is what makes the view stable. Every frame sees a different window
/// of the stream - about 800 new samples per frame at 48 kHz and 60 fps,
/// against a bucket of 164 samples. Anchored at `samples[0]`, the same audio
/// would be re-bucketed with a different phase on every frame: its min/max
/// would change although the audio did not, so the envelope shimmers instead
/// of scrolling, and a transient jumps between fixed x slots instead of
/// sliding.
///
/// Two things this relies on, both easy to break:
/// - `bucket_len` must be the same on every frame. It is derived from the
///   ringbuffer length, which is constant - not from `samples.len()`, which
///   a [`Transform`] may change.
/// - `total` must include the silence the buffer is pre-filled with, see
///   [`AudioBuffer::new`]. Otherwise the stream position of `samples[0]` is
///   negative until the recording is longer than the buffer.
fn aligned_envelope(samples: &[f32], total: u64, bucket_len: usize) -> (u64, Vec<Bucket>) {
    // saturating: a transformation may return more samples than were
    // recorded, which has no meaningful position in the stream
    let first = total.saturating_sub(samples.len() as u64);
    let anchor = first.next_multiple_of(bucket_len as u64);
    let skip = ((anchor - first) as usize).min(samples.len());
    (anchor, envelope_exact(&samples[skip..], bucket_len))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Deterministic signal that varies slowly compared to a bucket, so that
    /// moving the bucket boundaries does change the min/max values. A signal
    /// repeating within a single bucket would make the tests below pass no
    /// matter where the boundaries are.
    fn signal(len: usize) -> Vec<f32> {
        (0..len)
            .map(|i| (i as f32 / 997.0).sin() * 0.8 + (i as f32 / 37.0).sin() * 0.2)
            .collect()
    }

    #[test]
    fn buckets_keep_their_values_while_scrolling() {
        const BUCKET_LEN: usize = 164;
        const WINDOW: usize = 4096;
        // not a multiple of BUCKET_LEN: this is what used to shift the phase
        const ARRIVED: usize = 800;

        let stream = signal(WINDOW + ARRIVED);
        let (anchor_a, a) = aligned_envelope(&stream[..WINDOW], WINDOW as u64, BUCKET_LEN);
        let (anchor_b, b) =
            aligned_envelope(&stream[ARRIVED..], (WINDOW + ARRIVED) as u64, BUCKET_LEN);

        // Both frames must describe the audio they have in common with the
        // very same buckets, just at a different position in the stream.
        let shift = (anchor_b - anchor_a) as usize / BUCKET_LEN;
        assert!(shift > 0 && shift < a.len());
        for (i, bucket) in b.iter().take(a.len() - shift).enumerate() {
            assert_eq!(bucket.min, a[i + shift].min, "bucket {i}");
            assert_eq!(bucket.max, a[i + shift].max, "bucket {i}");
        }
    }

    #[test]
    fn buckets_are_anchored_to_the_stream_not_to_the_buffer() {
        const BUCKET_LEN: usize = 164;
        let samples = signal(4096);
        for arrived in [0, 1, 163, 164, 800] {
            let (anchor, buckets) = aligned_envelope(&samples, 4096 + arrived as u64, BUCKET_LEN);
            assert_eq!(anchor % BUCKET_LEN as u64, 0);
            // no trailing partial bucket
            assert!(anchor + (buckets.len() * BUCKET_LEN) as u64 <= 4096 + arrived as u64);
        }
    }

    #[test]
    fn survives_a_buffer_longer_than_the_recording() {
        // AudioBuffer counts its pre-filled silence, so this cannot happen
        // through the public API; guard against it regressing anyway, since
        // it silently wrapped the whole waveform off-screen in release mode.
        let (anchor, buckets) = aligned_envelope(&signal(4096), 100, 164);
        assert_eq!(anchor, 0);
        assert!(!buckets.is_empty());
    }

    #[test]
    fn handles_a_transformation_shorter_than_one_bucket() {
        let (_, buckets) = aligned_envelope(&signal(10), 262144, 164);
        assert!(buckets.is_empty());
    }
}