# rikorose/deepfilternet architecture

> Architecture diagram of the GitHub repository rikorose/deepfilternet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rikorose/deepfilternet
- Repository: https://github.com/rikorose/deepfilternet

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Train["train.py"]:::cli
        Enhance["enhance.py"]:::cli
        Scripts["scripts/"]:::cli
    end

    %% Core Library
    subgraph "Core Library (df)" 
        direction TB
        Config["config.py"]:::core
        IO["io.py"]:::core
        Checkpoint["checkpoint.py"]:::core

        subgraph "Model Definitions" 
            direction TB
            DF1["deepfilternet.py"]:::core
            DF2["deepfilternet2.py"]:::core
            DF3["deepfilternet3.py"]:::core
            DFMF["deepfilternetmf.py"]:::core
            MFUtils["multiframe.py"]:::core
            Modules["modules.py"]:::core
        end

        subgraph "Training Utilities"
            direction TB
            Loss["loss.py"]:::core
            LR["lr.py"]:::core
            ModelWrap["model.py"]:::core
            Eval["evaluation_utils.py"]:::core
        end

        Viz["visualization.py"]:::core
        Logger["logger.py"]:::core
        Utils["utils.py"]:::core
        Version["version.py"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ConfigFiles["dataset.cfg"]:::data
        HDF5["HDF5 Datasets"]:::data
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Torch["PyTorch/torchaudio"]:::ext
        PyDF["pyDF (STFT/ISTFT)"]:::ext
        H5py["h5py"]:::ext
        Numpy["numpy"]:::ext
        MPL["matplotlib"]:::ext
    end

    %% Data Flow - Training
    Train -->|invokes| Config
    Enhance -->|invokes| Config
    Scripts -->|imports| Config

    Config -->|loads settings| IO

    IO -->|reads HDF5| HDF5
    IO -->|yields batches| Loss
    Loss --> ModelWrap
    ModelWrap --> Checkpoint
    ModelWrap --> Eval
    Eval --> Viz

    %% Inference Path
    Enhance -->|reads WAV| IO
    IO -->|calls| PyDF
    PyDF -->|features| ModelWrap
    ModelWrap -->|processed| PyDF
    PyDF -->|writes WAV| Enhance

    %% Core module links
    Config --> Modules
    Modules --> DF1
    Modules --> DF2
    Modules --> DF3
    Modules --> DFMF
    DFMF --> MFUtils

    %% Scripts link to core
    Scripts -->|uses| ModelWrap
    Scripts -->|uses| Viz

    %% External dependency links
    IO --> H5py
    Loss --> Numpy
    Viz --> MPL
    ModelWrap --> Torch

    %% Click Events
    click Train "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/train.py"
    click Enhance "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/enhance.py"
    click Scripts "https://github.com/rikorose/deepfilternet/tree/main/DeepFilterNet/df/scripts/"
    click Config "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/config.py"
    click IO "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/io.py"
    click Checkpoint "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/checkpoint.py"
    click DF1 "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/deepfilternet.py"
    click DF2 "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/deepfilternet2.py"
    click DF3 "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/deepfilternet3.py"
    click DFMF "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/deepfilternetmf.py"
    click MFUtils "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/multiframe.py"
    click Modules "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/modules.py"
    click Loss "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/loss.py"
    click LR "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/lr.py"
    click ModelWrap "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/model.py"
    click Eval "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/evaluation_utils.py"
    click Viz "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/visualization.py"
    click Logger "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/logger.py"
    click Utils "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/utils.py"
    click Version "https://github.com/rikorose/deepfilternet/blob/main/DeepFilterNet/df/version.py"

    %% Styles
    classDef cli fill:#9f6,stroke:#393,stroke-width:1px
    classDef core fill:#6cf,stroke:#039,stroke-width:1px
    classDef data fill:#fc6,stroke:#c93,stroke-width:1px,stroke-dasharray: 5 5
    classDef ext fill:#ccc,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
