libspecbleach

C library for audio noise reduction and other spectral effects.

Table of Contents

• Background
• De-noise Algorithms
• Build
• Installation
• Build Options
• Usage Examples
• Development
• Contributing
• License

Background

This library is a standalone, modular spectral processing engine originally extracted from noise-repellent. It decouples DSP algorithms from any specific plugin framework, allowing for clean integration into C/C++ audio software.

The core architecture uses a unified spectral processor concept. The library implements advanced spectral denoising using efficient circular buffering (SbSpectralCircularBuffer) and modern STFT processing. It is designed to be extensible, supporting future additions like de-crackle or de-click algorithms.

De-noise Algorithms

The library implements a sophisticated spectral gating algorithm enhanced by several psychoacoustic and statistical techniques:

1. Spectral Gating & Subtraction

The fundamental noise reduction method uses spectral subtraction with proprietary framing and windowing to minimize artifacts.

2. 2D Denoising (Time-Frequency Filtering)

A Non-Local Means (NLM) algorithm filters the spectrogram in both time and frequency domains simultaneously. This preserves structural details of the signal while reducing musical noise and "burbling" artifacts often associated with simple spectral subtraction. Note: This feature is computationally intensive and benefits from SIMD acceleration (enabled in Release builds).

3. Masking Veto

To preserve transients and prevent over-processing, a psychoacoustic masking model estimates the auditory masking threshold. If the signal components are strong enough to mask the noise naturally, the "veto" system prevents unnecessary noise reduction, preserving the natural character of the audio.

4. Tonal Reduction

Specialized handling for tonal noise components allows for more aggressive reduction of static hums and whines without affecting broadband characteristics.

5. Transparent Whitening

The whitening feature (noise floor recovery) has been refined to be transparent at 0dB reduction, ensuring that the noise floor texture is natural and consistent with the reduction amount.

6. Adaptive Estimation

In addition to manual noise profile capture, the library supports adaptive noise floor estimation using algorithms like SPP-MMSE, Brandt, and Martin Minimum Statistics.

Build

To compile and install libspecbleach, you will need:

• A C compiling toolchain (GCC or Clang supporting C17)
• CMake (3.16 or newer)
• pkg-config (required when USE_SYSTEM_FFTW=ON)
• FFTW3 library (libfftw3f, or let CMake fetch it automatically)
• OpenMP for parallel processing (recommended for multi-threaded NLM 2D denoising):
  • macOS: brew install libomp
  • Linux: sudo apt install libomp-dev (Clang) or included with GCC
  • Windows: Included natively in MSVC (/openmp) and MinGW GCC (-fopenmp)
• libsndfile (optional, for test suite and demo tools)

Installation

git clone https://github.com/lucianodato/libspecbleach.git
cd libspecbleach

# Configure build (defaults to shared library)
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Compile
cmake --build build --config Release --parallel

# Install system-wide (installs libspecbleach.so, headers, and specbleach.pc)
sudo cmake --install build

Pkg-config Support: System installation installs specbleach.pc into your system's pkgconfig directory (e.g., /usr/lib/pkgconfig). Downstream applications can discover the library using pkg-config --modversion specbleach or CMake's pkg_check_modules().

Build Options

You can configure the build using -Doption=VALUE:

| Option | Default | Description | | :--- | :--- | :--- | | BUILD_SHARED_LIBS | ON | Build shared library (.so / .dylib / .dll) instead of static library | | SPECBLEACH_INSTALL | ON | Enable installation rules for library binaries, headers, and package config (.pc, .cmake) | | USE_SYSTEM_FFTW | ON | Link against system-installed libfftw3f. If set to OFF, CMake fetches and compiles static FFTW3 automatically | | ENABLE_AVX | ON | Enable AVX SIMD optimizations on x86_64 architectures | | ENABLE_TESTS | OFF | Build unit, integration, and audio regression test suite | | ENABLE_COVERAGE | OFF | Enable code coverage instrumentation | | ENABLE_EXAMPLES | OFF | Build demo executables (requires libsndfile) | | ENABLE_SANITIZERS | OFF | Enable AddressSanitizer and UndefinedBehaviorSanitizer |

[!IMPORTANT] Critical Performance Note for Packagers & Users: The advanced "2D Denoising" (NLM) feature is computationally intensive and relies heavily on SIMD vectorization and multi-core parallelization via OpenMP.

If OpenMP is missing at build time, NLM will fall back to single-threaded processing, which may cause high CPU utilization and audio dropouts (xruns) in real-time DAW environments.

Always ensure OpenMP runtime libraries are installed prior to running CMake:

• macOS: brew install libomp
• Linux (Ubuntu/Debian): sudo apt install libomp-dev
• Windows: OpenMP is built into MSVC and MinGW GCC.

You MUST configure with -DCMAKE_BUILD_TYPE=Release (or the compiler's equivalent optimization settings) for real-time performance. Debug or unoptimized builds will result in high CPU load.

Example: Building Static Library with Tests and Examples

cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DENABLE_TESTS=ON \
  -DENABLE_EXAMPLES=ON

cmake --build build --config Release --parallel

Usage Examples

Console demo applications demonstrate library usage. They require libsndfile to build:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_EXAMPLES=ON
cmake --build build --parallel

Manual Noise Profile

To process an audio file using a manually captured noise profile (first N frames):

./build/denoiser_demo --learn-frames 10 input.wav output.wav

Adaptive Mode

To use the adaptive noise estimator:

./build/denoiser_demo --adaptive input.wav output.wav

Full Options

./build/denoiser_demo \
  --adaptive \
  --reduction 20 \
  --whitening 50 \
  --smoothing 0.0 \
  input.wav output.wav

Development

Building for Development

For development builds with debug symbols and full test suite:

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_TESTS=ON -DENABLE_EXAMPLES=ON
cmake --build build --parallel

Code Formatting

The project uses clang-format. Format modified C files before submitting:

find src include -type f \( -name "*.c" -o -name "*.h" \) | xargs clang-format -i

Running Tests

Run the full CTest suite:

ctest --test-dir build --output-on-failure

Or run individual test executables:

./build/test_integration
./build/test_audio_file_regression # requires libsndfile

License

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

See LICENSE for more details.