lucianodato/libspecbleach
lucianodato/libspecbleach has 110 GitHub stars and 19 forks. GitHot measured 0 stars in 24 hours and +2 in 7 days. Last checked 2026-11-17 02:36 UTC. Last push 2026-10-17.
Measured star growth
- in 24h
- 0
- in 7 days
- +2
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
C library for audio noise reduction and other spectral effects
Creative & MediaREADME.md
Originallibspecbleach
C library for audio noise reduction and other spectral effects.
Table of Contents
- Background
- De-noise Algorithms
- Build
- Installation
- Build Options
- Quick Integration
- 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 is fully self-contained with zero external runtime dependencies—it includes a built-in worker pool for deterministic multi-threaded 2D denoising, efficient circular buffering (SbSpectralCircularBuffer), and vendored PFFFT for fast SIMD-accelerated spectral transforms. 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)
- A threading library (pthreads on POSIX; built-in on Windows)
- 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.pcinto your system'spkgconfigdirectory (e.g.,/usr/lib/pkgconfig). Downstream applications can discover the library usingpkg-config --modversion specbleachor CMake'spkg_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) |
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] Performance Note for Packagers & Users: The advanced "2D Denoising" (NLM) feature is computationally intensive and relies heavily on SIMD vectorization and multi-core parallelization through a built-in worker pool (no external threading runtime required).
The pool is created internally when the NLM smoother is initialized (owned by the spectral denoiser) and dispatches work with static, contiguous partitioning, keeping output deterministic across runs. Thread count defaults to 4 (see
NLM_NUM_THREADS_DEFAULTinsrc/shared/configurations.h) and can be tuned per instance throughNlmFilterConfig::num_threads.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
Quick Integration
#include <specbleach_denoiser.h>
// 1. CREATE — one instance per channel; frame_size_ms = STFT window (20-100)
specbleach_denoiser* denoiser =
specbleach_denoiser_initialize(sample_rate, 46.0f, 0u);
// Report latency to your host for delay compensation (stable after init)
uint32_t latency = specbleach_denoiser_get_latency(denoiser);
// 2. CONFIGURE — start from safe defaults; library copies everything
SpecbleachDenoiserParameters p = specbleach_denoiser_get_default_parameters();
p.learn_noise = SPECBLEACH_LEARN_ALL;
p.reduction_gain = 0.1f; // -20 dB
specbleach_denoiser_load_parameters(denoiser, &p, sizeof(p));
// 3. LEARN — feed blocks containing only noise (RT-safe call)
specbleach_denoiser_process(denoiser, nframes, in, out);
// 4. FINALIZE — profiles are only usable after learning turns OFF
p.learn_noise = SPECBLEACH_LEARN_OFF;
specbleach_denoiser_load_parameters(denoiser, &p, sizeof(p));
// 5. REDUCE — same call shape forever after; any block size (RT-safe)
specbleach_denoiser_process(denoiser, nframes, in, out);
// 6. CLEANUP (setup thread only, not RT-safe)
specbleach_denoiser_free(denoiser);
Buffers are plain planar float arrays of nframes length; output may alias
input. _process is real-time safe (no allocations, locks, or I/O);
parameter loads and create/destroy are not. A complete zero-dependency
example lives in examples/simple_embed.c.
Low-Latency Mode
For live use (live hosts), pass SPECBLEACH_INIT_LOW_LATENCY
at init with a 512-sample frame (512*1000/sample_rate ms). The denoiser
goes causal: the NLM look-ahead is removed and NLM/DFTT smoothing requests
are clamped to 1D temporal, so total latency equals the STFT frame alone —
~10.7 ms at 48 kHz, ~11.6 ms at 44.1 kHz (both under 20 ms). The frame
runs at 8x overlap (64-sample hop, Hann/Hann) for agile gain updates;
reported latency stays one frame:
float frame_ms = 512.0f * 1000.0f / (float)sample_rate;
specbleach_denoiser* denoiser = specbleach_denoiser_initialize(
sample_rate, frame_ms, SPECBLEACH_INIT_LOW_LATENCY);
// get_latency() reports 512: re-query once and compensate downstream.
Rules: the flag is init-time only (it changes latency/geometry, so it
cannot ride load_parameters); masking veto and transient protection stay
fully active (both are causal); zeropadding a 512 frame buys no real
frequency resolution (interpolation only) and is not recommended —
prefer the native 512 frame. flags = 0 preserves the default
full-latency behavior bit-for-bit.
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.