How rikorose/deepfilternet works
Project type and purpose
• Type: Python-based speech-enhancement framework and CLI tool.
• Purpose: Provide a library (df) for training, evaluating, visualizing, and running pretrained DeepFilterNet models using Deep Filtering on full-band audio (48 kHz).
DeepFilterNet folder structure
Top-level “DeepFilterNet” directory contains:
├─ pyproject.toml, requirements*.txt, setup files
└─ df (the Python package)
• __init__.py
• config.py – configuration loading (INI/JSON)
• io.py – audio and HDF5 I/O
• deepfilternet*.py – model definitions (Net1, Net2, Net3, multi-frame)
• modules.py – building blocks (convs, RNNs, attention)
• loss.py – training loss functions
• evaluation_utils.py – metrics (e.g., STOI)
• logger.py – logging setup
• lr.py – learning-rate schedulers
• model.py – wrapper to assemble model+optimizer
• train.py – training entry point
• enhance.py – real-time/CLI enhancement script
• visualization.py – plotting losses, spectrograms
• utils.py – misc helpers
• version.py – package version
└─ scripts/ – auxiliary CLI tools (data prep, export, tests…)
Major components
A. CLI Layer
– train.py (train entrypoint)
– enhance.py (enhance entrypoint)
– scripts/* (data prep, model_summary, plotting)
B. Core Library (“df” package)
– Config Engine (config.py)
– I/O Layer (io.py)
– Model Definitions (deepfilternet*.py + modules.py)
– Training Utilities (loss.py, lr.py, model.py, evaluation_utils.py)
– Visualization (visualization.py)
– Logging (logger.py)
– General Helpers (utils.py, version.py)
C. Data Layer
– HDF5 datasets on disk (speech, noise, RIR)
– Configuration files (dataset.json, config.ini)
D. External Dependencies
– PyTorch (torch, torchaudio)
– libDF Python binding (pyDF) for STFT/ISTFT
– h5py, numpy, matplotlib
Relationships and data flow
1. User invokes CLI (train.py or enhance.py).
2. CLI calls Config Engine → parses model & training/inference settings.
3. For training:
• Data Loader (df/io.py + pyDF-data) reads HDF5 → yields batches → transforms → model → loss → optimizer → checkpoint (df/model.py).
• evaluation_utils tracks metrics, visualization.py renders curves and spectrograms.
4. For enhancement:
• enhance.py loads model checkpoints → df/io.py reads WAV → pyDF binding computes STFT → model.apply() → ISTFT → writes output WAV.
5. Auxiliary scripts (prepare_data.py, export.py, plot_*.py) hook into the same core library.
Architectural patterns and design principles
• Modular layering: CLI → Core API → I/O → External libs
• Separation of concerns: config, I/O, model, training, evaluation, visualization in distinct modules
• Plugin-style scripts: all utilities import from df package
• Reuse of Rust-based libDF via Python binding for performance-critical STFT/ISTFT
Final checklist
[ ] Note on key configuration files (e.g., config.ini, dataset.json)