Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Visualizations

Authors
Affiliations
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley
The Eric and Wendy Schmidt Center for Data Science & Environment
University of California, Berkeley

The spectrogram player renders each audio clip as an interactive visualization. Switch between visualization types from the dropdown, adjust resolution, buffer, zoom, and capture the current view as a PNG.

Built-in Visualizations

Five visualization types are included and can be referenced by string name in the visualizations parameter:

NameDescription
'linear' (or 'spectrogram')Linear-frequency STFT magnitude spectrogram
'mel'Mel-scale spectrogram — compresses the frequency axis to better match human auditory perception
'log_frequency'Log-frequency spectrogram — more visual detail at lower frequencies, similar to a constant-Q transform
'bandpass'Bandpass spectrogram focused on 1–8 kHz (typical birdsong range)
'waveform'Time-domain waveform plot (amplitude vs. time, not a spectrogram)
Loading...
Loading...

The first item in the list is the default. Use selected:: prefix to override the default (e.g. ['linear', 'selected::mel', 'log_frequency']).


Capture

The capture button saves the current spectrogram/visualization as a PNG file. Configure it with:

BioacousticAnnotator(
    data='detections.csv',
    audio='recording.flac',
    capture='Save Spectrogram',
    capture_dir='spectrograms',
).open()

Standalone Usage

The visualization functions in jupyter_bioacoustic.utils.visualizations can be used outside the widget — for analysis, figures, or custom pipelines.

matrix shape: (256, 1995)
freq_min: 50.0 freq_max: 24000.0
freq_scale: log
matrix min: 0.0 max: 100.40672495176402
<Figure size 1200x400 with 1 Axes>

The vis.plot() helper renders any visualization dict as a matplotlib figure. It handles dB normalization, colormap rendering, and frequency-axis tick labels for linear, mel, and log scales.

Available functions: vis.spectrogram(), vis.mel(), vis.log_frequency(), vis.bandpass(), vis.waveform().

vis.render_png(matrix, width, cmap, dynamic_range_db) converts a raw 2D matrix to PNG bytes — useful when building custom visualizations that need colormap control without full matplotlib layout.

Custom Visualizations

Custom visualization functions can be passed directly to the visualizations parameter alongside built-in names. Each function must have the signature (mono, sr, width) and returns a dict with freq_min, freq_max, freq_scale and either

Both forms require freq_min, freq_max, and freq_scale ('linear', 'mel', or 'log'). Matrix returns can optionally include matrix_scale: 'db' to skip the dB conversion.

def my_custum_vis(mono: np.ndarray, sr: float, width: int) -> dict:
    ...
    return {
        'freq_min':  ...,    # min frequency
        'freq_max':  ...,    # max frequency
        'freq_scale':  ...,  # frequency scale: one of linear, mel, or log
        'png_bytes': ...,    # [Required if matrix is None] raw PNG image bytes
        'matrix': ...,       # [Required if png_bytes is None] a 2D numpy array (freq × time)
        'matrix_scale': ..., # [Optional] db or None - only works with 'matrix'
    }

Matrix Example

Loading...
Loading...

PNG Example

Loading...
Loading...

Third-party Visualizations

Any audio library can be wrapped as a custom visualization. The demo notebooks show integrations with:


OpenSoundscapes

Loading...
Loading...

Librosa

Loading...
Loading...

SciPy

Loading...
Loading...

See the Visualizations and 3rd Party Visualizations notebooks for complete examples.