A small command-line tool for processing and visualising audio recordings, combining a simple noise-reduction pipeline with waveform and spectrogram views.

It is designed for exploring the structure of recordings, showing how signal energy varies over time and frequency. The output combines a waveform view with a time–frequency spectrogram, making it easy to interpret timing, frequency content, and overall signal shape at a glance.

The tool is primarily intended for wildlife recordings, particularly bat recordings (time expansion and heterodyne), but can be used with any suitable WAV audio.

To run the application, first create and activate a virtual environment by running the following at the root of the project:

python -m venv venv
source ./venv/bin/activate

Then, install the project dependencies:

pip install --upgrade pip
pip install -e .

This assumes a Mac or Linux-based setup and should be modified if running on Windows.

Open a terminal window and run the following from the project folder:

source ./venv/bin/activate
python -m spectrogram --config config.json --input /path/to/audio/file.wav --spectrogram

A window should be displayed showing the chart:

Open a terminal window and run the following from the project folder:

source ./venv/bin/activate
python -m spectrogram --config config.json --input /path/to/audio/file.wav --noise-detection

A window should be displayed showing the chart:

To run an audio file through the noise reduction pipeline (see below), open a terminal window and run the following from the project folder:

source ./venv/bin/activate
python -m spectrogram --config config.json --input /path/to/audio/file.wav --output /path/to/output/file.wav --process

The tool includes a simple, repeatable audio-processing pipeline designed to make recordings clearer and easier to interpret.

It follows the same general approach as a manual workflow in tools like Audacity, but applies it consistently and automatically.

Each input recording is processed in the following stages:

The pipeline is intentionally simple and transparent:

• Repeatable — removes the need for manual selection of noise regions
• Interpretable — each step is easy to understand and adjust
• Non-destructive in spirit — preserves timing and structure of the original signal
• Practical — tuned for real-world field recordings rather than ideal conditions

Notes:

• This is a heuristic workflow, not a studio-grade restoration process
• It works best where recordings contain at least some gaps between calls
• The aim is clarity and consistency, not perfect noise removal

To reduce background noise automatically, the pipeline includes a simple noise-region detection step. This replaces the manual process of selecting a “quiet” section of audio (as you might do in Audacity).

The recording is divided into short, overlapping windows (typically 50 ms). For each window, two measurements are taken:

• Loudness (RMS amplitude) → Quieter windows are more likely to contain background noise only.
• Band energy ratio → The fraction of spectral energy within the expected signal band (for bat recordings, typically ~3.5–6.5 kHz after time expansion).

The band energy ratio is then used to identify the type of signal in the window:

• Low ratio → broadband noise / hiss
• High ratio → structured signal (e.g. bat calls)

A window is considered likely noise if it is both:

• Relatively quiet compared to the rest of the recording, and
• Relatively low in energy within the target band

Thresholds are determined using percentiles, so the detection adapts to each recording rather than relying on fixed values.

Neighbouring “noise” windows are merged into longer regions, and only regions above a minimum duration are kept. These regions are then used as the noise profile for subsequent noise reduction.

• This is a heuristic approach, not a guaranteed classification
• It works best when recordings contain genuine gaps between calls
• On dense or noisy recordings, it will tend to select the least signal-like sections rather than perfectly clean noise
• The goal is consistency and practicality, not perfect isolation

The config.json file in the root of the project contains configuration properties for the spectrogram viewer and processing pipeline.

The file has the following structure:

{
    "default": {

    },
    "heterodyne": {

    }
}

It's a dictionary of dictionaries, each one representing a named set of parameters. On the command line, the profile to use is specified using:

--profile "<name>"

This can be specified for the spectrogram plotting, noise detection and audio processing options, documented above. If no profile is specified, the default profile is used. For example, to process a file using the heterodyne processing parameters, the command line would be:

source ./venv/bin/activate
python -m spectrogram --config config.json --profile "heterodyne" --input /path/to/audio/file.wav --output /path/to/output/file.wav --process

The remainder of this section describes each of the parameters.

These parameters control how the tool identifies likely noise-only regions within a recording:

These parameters control the spectral noise reduction stage, where an estimated noise profile is subtracted from the signal in the frequency domain.

These parameters control the high-pass filtering stage, which removes low-frequency noise and focuses the signal on the frequency range of interest.

These parameters control the final normalisation step, which adjusts the overall signal level for consistency.

• Dave Walker - Initial work

To file issues or suggestions, please use the Issues page for this project on GitHub.

This project is licensed under the MIT License - see the LICENSE file for details