The Problem

Modern speech‑processing pipelines generate thousands of audio files that may contain noise, clipping, codec artefacts, or other degradations. Manually listening to each file is infeasible. AADD supplies a fast, frame‑level classifier that reports which degradation is present and where, enabling automatic quality gating for ASR/TTS training or post‑processing validation.

What This Does

AADD detects 12 degradation classes (e.g., background noise, reverberation, clipping, low‑pass, high‑pass, codec artefacts, packet loss, mains hum, clicks, pitch shift, time stretch) at a 20 ms resolution. The output is a per‑file verdict, a timeline of degradation probabilities, and an interactive HTML report that lets users tune a confidence threshold and inspect the clean‑audio fraction.

Key files:

  • aadd/cli.py – command‑line interface.
  • aadd/infer.py – loads the pretrained model (aadd/model.py) and runs inference.
  • aadd/features.py – extracts short‑time spectral features.
  • aadd/report.py – creates the visual report (docs/examples/report_public_sets.html).
  • aadd/train.py – training script for custom data.
  • aadd/compare.py – utilities for comparing two sets of predictions.

How It Is Wired

Entry point: aadd/cli.py.

  1. cli.py parses arguments (argparse) and dispatches to functions in aadd/cli.py (e.g., scan, train, compare).
  2. scan calls aadd/infer.infer_dir, which iterates over audio files.
  3. For each file, infer.py loads the model (aadd/model.py), extracts features via features.extract, and feeds them to the model to produce a frame‑level probability tensor.
  4. infer.py aggregates probabilities into a timeline and calls metrics.evaluate to compute per‑class scores.
  5. report.py consumes the timeline and scores, rendering an HTML page with waveform, spectrogram, and interactive timeline widgets.

The hub is scan in cli.py; it touches the filesystem (reads audio, writes report) and the network only when models are downloaded via model.load_pretrained. The widest blast radius is infer.py, as any change to the model architecture or feature extractor propagates to all downstream modules.

How To Use It

Setup

# Clone the repo
git clone https://github.com/moses-y/aadd
cd aadd

# Install dependencies (uses pyproject.toml)
pip install .

# Optional: build the Docker image
docker build -t aadd .

Configuration

No external config files are required; the pretrained model is pulled automatically from the Hugging Face hub (gertelrina/aadd). All parameters are set via CLI flags.

Running

# Scan a directory and produce an interactive report
aadd scan my_dataset/ --report report.html

The command writes report.html and a JSON summary in the current directory. Use the web interface to adjust thresholds and inspect individual files.

Real‑World Use

A data‑engineering team can integrate AADD into the nightly data‑quality pipeline:

# CI step
aadd scan $DATA_DIR --report $OUTPUT_DIR/report.html
if grep -q "ERROR" $OUTPUT_DIR/report.html; then
    echo "Degradation detected – rejecting dataset"
    exit 1
fi

The report can be stored in a data catalog and referenced by downstream training jobs.

Code Health & Issues

  • Low (1) – pyproject.toml defines dependencies but no lockfile; builds may vary across environments.
  • Low (1) – Dockerfile pulls python:3.9-slim and installs via pip install . without pinning sub‑dependencies.
  • Low (1) – CI (.github/workflows/ci.yml) runs tests, but the repository lacks a Makefile or setup.py, which could improve reproducibility.

The test suite (tests/) contains 13 files covering data ingestion, feature extraction, inference, and report generation. CI passes on all forks of the original project, ensuring baseline quality.

The Bottom Line

AADD provides a ready‑to‑use, open‑source tool for fine‑grained audio degradation detection. Its modular design allows quick integration into data‑quality pipelines, and the Docker image simplifies deployment. The absence of a lockfile is a minor drawback that can be mitigated with a poetry.lock or pip‑freeze. Teams working with large speech corpora and requiring automated quality gates will find AADD a practical addition to their stack.