Struct WaveformVisualizer 

pub struct WaveformVisualizer<'a> { /* private fields */ }

Builder that renders mono audio samples as a waveform image.

Samples are expected as amplitudes in [-1.0, 1.0], the usual DSP convention; other symmetric ranges work too since the y-axis fits the data unless Self::y_range fixes it. For interleaved stereo data, split it with crate::deinterleave_stereo first and render each channel separately.

What the image shows

An image is far narrower than the audio is long: one second at 44.1 kHz is dozens of samples per pixel column already. A column therefore is a filled bar from the smallest to the largest sample it covers, as in audio editors such as Audacity - the shape is the peak amplitude over time, and the oscillation within a column is deliberately not resolved. A lighter bar inside shows the RMS of the column, i.e. how loud it is.

Drawing a line through every n-th sample instead would undersample the signal by orders of magnitude: peaks between two picked samples vanish, and what is left aliases into a pattern that is not in the audio.

For real-time visualization see crate::live.

Example

use audio_visualizer::WaveformVisualizer;

let samples: Vec<f32> = vec![0.0, 0.5, -0.5, 0.3];
WaveformVisualizer::new(&samples)
    .sample_rate(44100.0)
    .write_png("waveform.png")
    .unwrap();

Implementations

impl<'a> Waveform<'a>

pub const fn new(samples: &'a [f32]) -> Self

Creates a waveform visualization of the given mono samples.

pub const fn sample_rate(self, sample_rate_hz: f32) -> Self

Labels the x-axis with seconds instead of sample indices.

pub const fn y_range(self, range: Range<f32>) -> Self

Fixes the y-axis to the given range instead of fitting it to the data. Amplitudes outside the range are clipped to its bounds.

This makes images of different signals comparable: with -1.0..1.0, every image shows the full scale of [-1.0, 1.0] samples.

pub const fn size(self, width: u32, height: u32) -> Self

Sets the image dimensions in pixels. Default: 1400x400.

pub fn title(self, title: impl Into<String>) -> Self

Sets a title displayed above the chart.

pub fn to_svg(&self) -> Result<String, Error>

Renders the waveform to an SVG string.

pub fn write_png(&self, path: impl AsRef<Path>) -> Result<(), Error>

Renders the waveform and writes it as PNG file, creating missing parent directories.

Trait Implementations

impl<'a> Clone for Waveform<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Waveform<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.