{"id":15030326,"url":"https://github.com/rikorose/deepfilternet","last_synced_at":"2025-05-14T01:10:39.582Z","repository":{"id":39622319,"uuid":"415655246","full_name":"Rikorose/DeepFilterNet","owner":"Rikorose","description":"Noise supression using deep filtering","archived":false,"fork":false,"pushed_at":"2024-10-17T08:35:11.000Z","size":179177,"stargazers_count":2993,"open_issues_count":43,"forks_count":279,"subscribers_count":35,"default_branch":"main","last_synced_at":"2025-04-23T17:18:55.566Z","etag":null,"topics":["audio","deep-learning","noise-suppression","pytorch","rust","speech","speech-enhancement"],"latest_commit_sha":null,"homepage":"https://huggingface.co/spaces/hshr/DeepFilterNet2","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rikorose.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-10T17:32:57.000Z","updated_at":"2025-04-23T07:25:30.000Z","dependencies_parsed_at":"2024-10-19T08:25:33.512Z","dependency_job_id":"63961426-c55e-4170-8511-7a29adff3528","html_url":"https://github.com/Rikorose/DeepFilterNet","commit_stats":{"total_commits":1594,"total_committers":17,"mean_commits":93.76470588235294,"dds":"0.26348808030112925","last_synced_commit":"d375b2d8309e0935d165700c91da9de862a99c31"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikorose%2FDeepFilterNet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikorose%2FDeepFilterNet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikorose%2FDeepFilterNet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rikorose%2FDeepFilterNet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rikorose","download_url":"https://codeload.github.com/Rikorose/DeepFilterNet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254049246,"owners_count":22006025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","deep-learning","noise-suppression","pytorch","rust","speech","speech-enhancement"],"created_at":"2024-09-24T20:13:06.475Z","updated_at":"2025-05-14T01:10:34.562Z","avatar_url":"https://github.com/Rikorose.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DeepFilterNet\nA Low Complexity Speech Enhancement Framework for Full-Band Audio (48kHz) using on Deep Filtering.\n\n![deepfilternet3](https://user-images.githubusercontent.com/16517898/225623209-a54fea75-ca00-404c-a394-c91d2d1146d2.svg)\n\nFor PipeWire integration as a virtual noise suppression microphone look [here](https://github.com/Rikorose/DeepFilterNet/blob/main/ladspa/README.md).\n\n### Demo\n\nhttps://github.com/Rikorose/DeepFilterNet/assets/16517898/79679fd7-de73-4c22-948c-891927c7d2ca\n\nTo run the demo (linux only) use:\n```bash\ncargo +nightly run -p df-demo --features ui --bin df-demo --release\n```\n\n### News\n\n- New DeepFilterNet Demo: *DeepFilterNet: Perceptually Motivated Real-Time Speech Enhancement*\n  - Paper: https://arxiv.org/abs/2305.08227\n  - Video: https://youtu.be/EO7n96YwnyE\n\n- New Multi-Frame Filtering Paper: *Deep Multi-Frame Filtering for Hearing Aids*\n  - Paper: https://arxiv.org/abs/2305.08225\n\n- Real-time version and a LADSPA plugin\n  - [Pre-compiled binary](#deep-filter), no python dependencies. Usage: `deep-filter audio-file.wav`\n  - [LADSPA plugin](ladspa/) with pipewire filter-chain integration for real-time noise reduction on your mic.\n\n- DeepFilterNet2 Paper: *DeepFilterNet2: Towards Real-Time Speech Enhancement on Embedded Devices for Full-Band Audio*\n  - Paper: https://arxiv.org/abs/2205.05474\n  - Samples: https://rikorose.github.io/DeepFilterNet2-Samples/\n  - Demo: https://huggingface.co/spaces/hshr/DeepFilterNet2\n\n- Original DeepFilterNet Paper: *DeepFilterNet: A Low Complexity Speech Enhancement Framework for Full-Band Audio based on Deep Filtering*\n  - Paper: https://arxiv.org/abs/2110.05588\n  - Samples: https://rikorose.github.io/DeepFilterNet-Samples/\n  - Demo: https://huggingface.co/spaces/hshr/DeepFilterNet\n  - Video Lecture: https://youtu.be/it90gBqkY6k\n\n## Usage\n\n### deep-filter\n\nDownload a pre-compiled deep-filter binary from the [release page](https://github.com/Rikorose/DeepFilterNet/releases/).\nYou can use `deep-filter` to suppress noise in noisy .wav audio files. Currently, only wav files with a sampling rate of 48kHz are supported.\n\n```bash\nUSAGE:\n    deep-filter [OPTIONS] [FILES]...\n\nARGS:\n    \u003cFILES\u003e...\n\nOPTIONS:\n    -D, --compensate-delay\n            Compensate delay of STFT and model lookahead\n    -h, --help\n            Print help information\n    -m, --model \u003cMODEL\u003e\n            Path to model tar.gz. Defaults to DeepFilterNet2.\n    -o, --out-dir \u003cOUT_DIR\u003e\n            [default: out]\n    --pf\n            Enable postfilter\n    -v, --verbose\n            Logging verbosity\n    -V, --version\n            Print version information\n```\n\nIf you want to use the pytorch backend e.g. for GPU processing, see further below for the Python usage.\n\n### DeepFilterNet Framework\n\nThis framework supports Linux, MacOS and Windows. Training is only tested under Linux. The framework is structured as follows:\n\n* `libDF` contains Rust code used for data loading and augmentation.\n* `DeepFilterNet` contains DeepFilterNet code training, evaluation and visualization as well as pretrained model weights.\n* `pyDF` contains a Python wrapper of libDF STFT/ISTFT processing loop.\n* `pyDF-data` contains a Python wrapper of libDF dataset functionality and provides a pytorch data loader.\n* `ladspa` contains a LADSPA plugin for real-time noise suppression.\n* `models` contains pretrained for usage in DeepFilterNet (Python) or libDF/deep-filter (Rust)\n\n### DeepFilterNet Python: PyPI\n\nInstall the DeepFilterNet Python wheel via pip:\n```bash\n# Install cpu/cuda pytorch (\u003e=1.9) dependency from pytorch.org, e.g.:\npip install torch torchaudio -f https://download.pytorch.org/whl/cpu/torch_stable.html\n# Install DeepFilterNet\npip install deepfilternet\n# Or install DeepFilterNet including data loading functionality for training (Linux only)\npip install deepfilternet[train]\n```\n\nTo enhance noisy audio files using DeepFilterNet run\n```bash\n# Specify an output directory with --output-dir [OUTPUT_DIR]\ndeepFilter path/to/noisy_audio.wav\n```\n\n### Manual Installation\n\nInstall cargo via [rustup](https://rustup.rs/). Usage of a `conda` or `virtualenv` recommended.\nPlease read the comments and only execute the commands that you need.\n\nInstallation of python dependencies and libDF:\n```bash\ncd path/to/DeepFilterNet/  # cd into repository\n# Recommended: Install or activate a python env\n# Mandatory: Install cpu/cuda pytorch (\u003e=1.8) dependency from pytorch.org, e.g.:\npip install torch torchaudio -f https://download.pytorch.org/whl/cpu/torch_stable.html\n# Install build dependencies used to compile libdf and DeepFilterNet python wheels\npip install maturin poetry\n\n#  Install remaining DeepFilterNet python dependencies\n# *Option A:* Install DeepFilterNet python wheel globally within your environment. Do this if you want use\n# this repos as is, and don't want to develop within this repository.\npoetry -C DeepFilterNet install -E train -E eval\n# *Option B:* If you want to develop within this repo, install only dependencies and work with the repository version\npoetry -C DeepFilterNet install -E train -E eval --no-root\nexport PYTHONPATH=$PWD/DeepFilterNet # And set the python path correctly\n\n# Build and install libdf python package required for enhance.py\nmaturin develop --release -m pyDF/Cargo.toml\n# *Optional*: Install libdfdata python package with dataset and dataloading functionality for training\n# Required build dependency: HDF5 headers (e.g. ubuntu: libhdf5-dev)\nmaturin develop --release -m pyDF-data/Cargo.toml\n# If you have troubles with hdf5 you may try to build and link hdf5 statically:\nmaturin develop --release --features hdf5-static -m pyDF-data/Cargo.toml\n```\n\n### Use DeepFilterNet from command line\n\nTo enhance noisy audio files using DeepFilterNet run\n```bash\n$ python DeepFilterNet/df/enhance.py --help\nusage: enhance.py [-h] [--model-base-dir MODEL_BASE_DIR] [--pf] [--output-dir OUTPUT_DIR] [--log-level LOG_LEVEL] [--compensate-delay]\n                  noisy_audio_files [noisy_audio_files ...]\n\npositional arguments:\n  noisy_audio_files     List of noise files to mix with the clean speech file.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --model-base-dir MODEL_BASE_DIR, -m MODEL_BASE_DIR\n                        Model directory containing checkpoints and config.\n                        To load a pretrained model, you may just provide the model name, e.g. `DeepFilterNet`.\n                        By default, the pretrained DeepFilterNet2 model is loaded.\n  --pf                  Post-filter that slightly over-attenuates very noisy sections.\n  --output-dir OUTPUT_DIR, -o OUTPUT_DIR\n                        Directory in which the enhanced audio files will be stored.\n  --log-level LOG_LEVEL\n                        Logger verbosity. Can be one of (debug, info, error, none)\n  --compensate-delay, -D\n                        Add some paddig to compensate the delay introduced by the real-time STFT/ISTFT implementation.\n\n# Enhance audio with original DeepFilterNet\npython DeepFilterNet/df/enhance.py -m DeepFilterNet path/to/noisy_audio.wav\n\n# Enhance audio with DeepFilterNet2\npython DeepFilterNet/df/enhance.py -m DeepFilterNet2 path/to/noisy_audio.wav\n```\n\n### Use DeepFilterNet within your Python script\n\n```py\nfrom df import enhance, init_df\n\nmodel, df_state, _ = init_df()  # Load default model\nenhanced_audio = enhance(model, df_state, noisy_audio)\n```\n\nSee [here](https://github.com/Rikorose/DeepFilterNet/blob/main/scripts/external_usage.py) for a full example.\n\n### Training\n\nThe entry point is `DeepFilterNet/df/train.py`. It expects a data directory containing HDF5 dataset\nas well as a dataset configuration json file.\n\nSo, you first need to create your datasets in HDF5 format. Each dataset typically only\nholds training, validation, or test set of noise, speech or RIRs.\n```py\n# Install additional dependencies for dataset creation\npip install h5py librosa soundfile\n# Go to DeepFilterNet python package\ncd path/to/DeepFilterNet/DeepFilterNet\n# Prepare text file (e.g. called training_set.txt) containing paths to .wav files\n#\n# usage: prepare_data.py [-h] [--num_workers NUM_WORKERS] [--max_freq MAX_FREQ] [--sr SR] [--dtype DTYPE]\n#                        [--codec CODEC] [--mono] [--compression COMPRESSION]\n#                        type audio_files hdf5_db\n#\n# where:\n#   type: One of `speech`, `noise`, `rir`\n#   audio_files: Text file containing paths to audio files to include in the dataset\n#   hdf5_db: Output HDF5 dataset.\npython df/scripts/prepare_data.py --sr 48000 speech training_set.txt TRAIN_SET_SPEECH.hdf5\n```\nAll datasets should be made available in one dataset folder for the train script.\n\nThe dataset configuration file should contain 3 entries: \"train\", \"valid\", \"test\". Each of those\ncontains a list of datasets (e.g. a speech, noise and a RIR dataset). You can use multiple speech\nor noise dataset. Optionally, a sampling factor may be specified that can be used to over/under-sample\nthe dataset. Say, you have a specific dataset with transient noises and want to increase the amount\nof non-stationary noises by oversampling. In most cases you want to set this factor to 1.\n\n\u003cdetails\u003e\n  \u003csummary\u003eDataset config example:\u003c/summary\u003e\n\u003cp\u003e\n  \n`dataset.cfg`\n\n```json\n{\n  \"train\": [\n    [\n      \"TRAIN_SET_SPEECH.hdf5\",\n      1.0\n    ],\n    [\n      \"TRAIN_SET_NOISE.hdf5\",\n      1.0\n    ],\n    [\n      \"TRAIN_SET_RIR.hdf5\",\n      1.0\n    ]\n  ],\n  \"valid\": [\n    [\n      \"VALID_SET_SPEECH.hdf5\",\n      1.0\n    ],\n    [\n      \"VALID_SET_NOISE.hdf5\",\n      1.0\n    ],\n    [\n      \"VALID_SET_RIR.hdf5\",\n      1.0\n    ]\n  ],\n  \"test\": [\n    [\n      \"TEST_SET_SPEECH.hdf5\",\n      1.0\n    ],\n    [\n      \"TEST_SET_NOISE.hdf5\",\n      1.0\n    ],\n    [\n      \"TEST_SET_RIR.hdf5\",\n      1.0\n    ]\n  ]\n}\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\nFinally, start the training script. The training script may create a model `base_dir` if not\nexisting used for logging, some audio samples, model checkpoints, and config. If no config file is\nfound, it will create a default config. See\n[DeepFilterNet/pretrained_models/DeepFilterNet](https://github.com/Rikorose/DeepFilterNet/blob/main/DeepFilterNet/pretrained_models/DeepFilterNet/config.ini)\nfor a config file.\n```py\n# usage: train.py [-h] [--debug] data_config_file data_dir base_dir\npython df/train.py path/to/dataset.cfg path/to/data_dir/ path/to/base_dir/\n```\n\n## Citation Guide\n\nTo reproduce any metrics, we recomend to use the python implementation via `pip install deepfilternet`.\n\nIf you use this framework, please cite: *DeepFilterNet: A Low Complexity Speech Enhancement Framework for Full-Band Audio based on Deep Filtering*\n```bibtex\n@inproceedings{schroeter2022deepfilternet,\n  title={{DeepFilterNet}: A Low Complexity Speech Enhancement Framework for Full-Band Audio based on Deep Filtering}, \n  author = {Schröter, Hendrik and Escalante-B., Alberto N. and Rosenkranz, Tobias and Maier, Andreas},\n  booktitle={ICASSP 2022 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP)},\n  year={2022},\n  organization={IEEE}\n}\n```\n\nIf you use the DeepFilterNet2 model, please cite: *DeepFilterNet2: Towards Real-Time Speech Enhancement on Embedded Devices for Full-Band Audio*\n\n```bibtex\n@inproceedings{schroeter2022deepfilternet2,\n  title = {{DeepFilterNet2}: Towards Real-Time Speech Enhancement on Embedded Devices for Full-Band Audio},\n  author = {Schröter, Hendrik and Escalante-B., Alberto N. and Rosenkranz, Tobias and Maier, Andreas},\n  booktitle={17th International Workshop on Acoustic Signal Enhancement (IWAENC 2022)},\n  year = {2022},\n}\n```\n\nIf you use the DeepFilterNet3 model, please cite: *DeepFilterNet: Perceptually Motivated Real-Time Speech Enhancement*\n\n```bibtex\n@inproceedings{schroeter2023deepfilternet3,\n  title = {{DeepFilterNet}: Perceptually Motivated Real-Time Speech Enhancement},\n  author = {Schröter, Hendrik and Rosenkranz, Tobias and Escalante-B., Alberto N. and Maier, Andreas},\n  booktitle={INTERSPEECH},\n  year = {2023},\n}\n```\n\nIf you use the multi-frame beamforming algorithms. please cite *Deep Multi-Frame Filtering for Hearing Aids*\n\n```bibtex\n@inproceedings{schroeter2023deep_mf,\n  title = {Deep Multi-Frame Filtering for Hearing Aids},\n  author = {Schröter, Hendrik and Rosenkranz, Tobias and Escalante-B., Alberto N. and Maier, Andreas},\n  booktitle={INTERSPEECH},\n  year = {2023},\n}\n```\n\n## License\n\nDeepFilterNet is free and open source! All code in this repository is dual-licensed under either:\n\n* MIT License ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))\n* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))\n\nat your option. This means you can select the license you prefer!\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frikorose%2Fdeepfilternet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frikorose%2Fdeepfilternet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frikorose%2Fdeepfilternet/lists"}