Skip to content

Commit fc5697d

Browse files
haoxiangsnrhaoxiangsnr
committed
docs,build: update README, installation guide, and switch to hatchling/uv for packaging
- Major rewrite of README.md for clarity, quick start, and citation - Update installation guide to recommend uv and add detailed steps for both uv and conda/pip - Switch build backend to hatchling in pyproject.toml, add dependencies and extras for GPU, test, docs, build - Add data/ to .gitignore These changes modernize the setup, improve reproducibility, and clarify usage for new users.
1 parent 9f285d3 commit fc5697d

File tree

4 files changed

+241
-107
lines changed

4 files changed

+241
-107
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ _build/
88
*.csv
99
core.*
1010
tmp/
11+
data/
1112

1213
# Ruff
1314
.ruff_cache/

‎README.md‎

Lines changed: 141 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,155 @@
1-
<!-- PROJECT SHIELDS -->
2-
<!--
3-
*** I'm using markdown "reference style" links for readability.
4-
*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
5-
*** See the bottom of this document for the declaration of the reference variables
6-
*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
7-
*** https://www.markdownguide.org/basic-syntax/#reference-style-links
8-
-->
9-
[![Stargazers][stars-shield]][stars-url]
10-
[![Forks][forks-shield]][forks-url]
11-
[![Contributors][contributors-shield]][contributors-url]
12-
[![Issues][issues-shield]][issues-url]
13-
[![MIT License][license-shield]][license-url]
14-
15-
<!-- PROJECT LOGO -->
16-
<br />
17-
<div align="center">
18-
<h3 align="center">Spiking-FullSubNet</h3>
19-
20-
<p align="center">
21-
Intel N-DNS Challenge Algorithmic Track Winner
22-
<br />
23-
<a href="https://haoxiangsnr.github.io/spiking-fullsubnet/"><strong>Explore the docs »</strong></a>
24-
<br />
25-
<br />
26-
<a href="https://github.com/haoxiangsnr/spiking-fullsubnet/">View Demo</a>
27-
·
28-
<a href="https://github.com/haoxiangsnr/spiking-fullsubnet/issues">Report Bug</a>
29-
·
30-
<a href="https://github.com/haoxiangsnr/spiking-fullsubnet/issues">Request Feature</a>
31-
</p>
32-
</div>
33-
34-
35-
<!-- ABOUT THE PROJECT -->
36-
## About The Project
37-
38-
![Spiking-FullSubNet](./docs/source/images/project_image.png)
39-
40-
We are proud to announce that Spiking-FullSubNet has emerged as the winner of Intel N-DNS Challenge Track 1 (Algorithmic). Please refer to our [brief write-up here](./Spiking-FullSubNet.pdf) for more details. This repository serves as the official home of the Spiking-FullSubNet implementation. Here, you will find:
41-
42-
- A PyTorch-based implementation of the Spiking-FullSubNet model.
1+
# Spiking-FullSubNet
2+
3+
Spiking-FullSubNet is the winner solution of Intel N-DNS Challenge Track 1 (Algorithmic). This repository serves as the official home of the Spiking-FullSubNet implementation. Here, you will find:
4+
5+
- A PyTorch-based implementation of the Spiking-FullSubNet model described in our paper "Toward Ultralow-Power Neuromorphic Speech Enhancement With Spiking-FullSubNet".
436
- Scripts for training the model and evaluating its performance.
447
- The pre-trained models in the `model_zoo` directory, ready to be further fine-tuned on the other datasets.
45-
46-
<!---
47-
We are actively working on improving the documentation, fixing bugs and removing redundancies. Please feel free to raise an issue or submit a pull request if you have suggestions for enhancements.
48-
Our team is diligently working on a comprehensive paper that will delve into the intricate details of Spiking-FullSuNet's architecture, its operational excellence, and the broad spectrum of its potential applications. Please stay tuned!
49-
-->
8+
- The frozen version of the solution used in the Intel N-DNS Challenge in the `38fe020` commit.
509

5110
## Updates
5211

53-
[2024-02-26] Currently, our repo contains two versions of the code:
12+
- 2026-01-27: The `main` branch shows the implementation of the Spiking-FullSubNet model as described in our published paper "Toward Ultralow-Power Neuromorphic Speech Enhancement With Spiking-FullSubNet", which includes several improvements and optimizations over the challenge version. We recommend using this branch for the citation and further research.
13+
- 2024-02-26: The **frozen version**, which serves as a backup for the submitted solution used in the Intel N-DNS Challenge. This solution has been checked and verified by Intel during the challenge. If you need to check the experimental results from that time, please refer to this specific commit: [38fe020](https://github.com/haoxiangsnr/spiking-fullsubnet/tree/38fe020cdb803d2fdc76a0df4b06311879c8e370). There you will find everything you need. After switching to this commit, you can place the checkpoints from the `model_zoo` into the `exp` directory and use `-M test` for inference or `-M train` to retrain the model. After challenge, we made some improvements and optimizations to the solution and published a paper (IEEE TNNLS) based on these improvements. Please check the `main` branch for the published paper version.
14+
15+
## Quick Start
16+
17+
You can either clone the repository, setup an environment and start with the scripts, or directly open in Colab (under construction).
18+
19+
## Environment Setup
20+
21+
We really like [uv](https://docs.astral.sh/uv/) and recommend using it as your package manager. But feel free to use whichever you prefer.
5422

55-
1. The **frozen version**, which serves as a backup for the code used in a previous competition. However, due to a restructuring in the `audiozen` directory, this version can no longer be directly used for inference. If you need to verify the experimental results from that time, please refer to this specific commit: [38fe020](https://github.com/haoxiangsnr/spiking-fullsubnet/tree/38fe020cdb803d2fdc76a0df4b06311879c8e370). There you will find everything you need. After switching to this commit, you can place the checkpoints from the `model_zoo` into the `exp` directory and use `-M test` for inference or `-M train` to retrain the model.
23+
> [!TIP]
24+
> uv is significantly faster (10~100x) than pip and handles dependency resolution more reliably.
25+
> The `uv.lock` file ensures reproducible installations across different machines.
5626
57-
2. The **latest version** of the code has undergone some restructuring and optimization to make it more understandable for readers. We've also introduced `acceleate` to assist with better training practices. We believe you can follow the instructions in the help documentation to run the training code directly. The pre-trained model checkpoints and a more detailed paper will be released by next weekend, so please stay tuned for that.
5827

28+
```bash
29+
# Clone the repository
30+
git clone git@github.com:haoxiangsnr/spiking-fullsubnet.git && cd spiking-fullsubnet
5931

32+
# [Optional] Install uv
33+
# Check https://docs.astral.sh/uv/ for other installation methods
34+
curl -LsSf https://astral.sh/uv/install.sh | sh
6035

61-
## Documentation
36+
# Install all dependencies (creates .venv automatically)
37+
# This will:
38+
# - Create a virtual environment in `.venv`
39+
# - Install all dependencies from `uv.lock`
40+
# - Install `audiozen` folder in editable mode so you can import it everywhere
41+
uv sync --all-extras
6242

63-
See the [Documentation](https://haoxiangsnr.github.io/spiking-fullsubnet/) for installation and usage. Our team is actively working to improve the documentation. Please feel free to raise an issue or submit a pull request if you have suggestions for enhancements.
43+
# Activate the virtual environment
44+
source .venv/bin/activate
45+
```
46+
47+
If you prefer Conda/pip, you can still use the traditional approach:
48+
49+
```bash
50+
git clone git@github.com:haoxiangsnr/spiking-fullsubnet.git && cd spiking-fullsubnet
51+
52+
conda create --name spiking-fullsubnet python=3.10
53+
conda activate spiking-fullsubnet
54+
55+
# torch==2.1.1 and torch==2.10 have been tested to work well with this codebase
56+
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
57+
58+
# Install other dependencies and the `audiozen` folder in editable mode
59+
# Please check the `pyproject.toml` for the full list of dependencies
60+
pip install -e .
61+
```
62+
63+
## Inference on Validation Set
64+
65+
Since the official test set requires a long time (10 hours+) for inference on a single GPU,
66+
we provide a mini-validation set to quickly verify. The validation set contains 341 noisy-clean pairs generated in the same way as the official test set. In our experience, performance gains on this set are highly positively correlated with the official test set.
67+
68+
```bash
69+
# Download validation set from Github Releases
70+
cd <your_project_root>
71+
mkdir data && cd data
72+
73+
# Download and extract validation set
74+
wget https://github.com/haoxiangsnr/spiking-fullsubnet/releases/download/data/validation_set.tar.gz
75+
tar -xzvf validation_set.tar.gz
76+
77+
# folder structure:
78+
.
79+
└── data
80+
├── validation_set
81+
│ ├── clean
82+
│ │ ├── clean_fileid_119.wav
83+
│ │ ├── clean_fileid_165.wav
84+
│ │ └── clean_fileid_7.wav
85+
│ ├── noise
86+
│ │ ├── noise_fileid_27.wav
87+
│ │ ├── noise_fileid_312.wav
88+
│ │ └── noise_fileid_4.wav
89+
│ └── noisy
90+
│ ├── book_00588_chp_0003_..._fileid_115.wav
91+
│ ├── book_09739_chp_0003_..._fileid_275.wav
92+
│ └── German_Wikiped_..._fileid_246.wav
93+
└── validation_set.tar.gz
94+
```
95+
96+
To run inference on the validation set using the pre-trained model, use the following command:
97+
98+
```bash
99+
cd <your_project_root>
100+
101+
# Download pre-trained model from Github Releases
102+
wget https://github.com/haoxiangsnr/spiking-fullsubnet/releases/download/ckpt-epoch-188/epoch_0188.zip
103+
104+
# Unzip the pre-trained model to the correct directory
105+
mkdir -p recipes/intel_ndns/spiking_fullsubnet_v2/exp/middle-model__partition-0-32-128-256__grouping-8-32-64__deep-filtering-5-3-1__synops-1e-8/checkpoints/
106+
107+
unzip epoch_0188.zip -d recipes/intel_ndns/spiking_fullsubnet_v2/exp/middle-model__partition-0-32-128-256__grouping-8-32-64__deep-filtering-5-3-1__synops-1e-8/checkpoints/epoch_0188
108+
109+
# Inference on validation set
110+
accelerate launch --multi_gpu \
111+
--num_processes=4 \
112+
--gpu_ids 0,1,2,3 \
113+
--main_process_port 46601 \
114+
run.py \
115+
--config_path conf/middle-model__partition-0-32-128-256__grouping-8-32-64__deep-filtering-5-3-1__synops-1e-8.yaml \
116+
--eval_batch_size 4 \
117+
--resume_from_checkpoint /home/xhao/proj/spiking-fullsubnet/recipes/intel_ndns/spiking_fullsubnet_v2/exp/middle-model__partition-0-32-128-256__grouping-8-32-64__deep-filtering-5-3-1__synops-1e-8/checkpoints/epoch_0188 \
118+
--do_eval true
119+
```
120+
121+
Depending on your software environment, you may have the results like below:
122+
123+
| set | si_sdr | P808 | OVRL | SIG | BAK |
124+
| ---------: | ------: | ------: | ------: | ------: | ------: |
125+
| validation | 15.0127 | 3.61135 | 3.01281 | 3.33227 | 3.93021 |
126+
127+
## Citation
128+
129+
If you find this repository useful for your research, please consider citing the following papers:
130+
131+
```bibtex
132+
@ARTICLE{hao2025toward,
133+
author={Hao, Xiang and Ma, Chenxiang and Yang, Qu and Wu, Jibin and Tan, Kay Chen},
134+
journal={IEEE Transactions on Neural Networks and Learning Systems},
135+
title={Toward Ultralow-Power Neuromorphic Speech Enhancement With Spiking-FullSubNet},
136+
year={2025},
137+
volume={36},
138+
number={9},
139+
pages={17350-17364},
140+
doi={10.1109/TNNLS.2025.3566021}}
141+
142+
@INPROCEEDINGS{hao2024when,
143+
author={Hao, Xiang and Ma, Chenxiang and Yang, Qu and Tan, Kay Chen and Wu, Jibin},
144+
booktitle={2024 IEEE Conference on Artificial Intelligence (CAI)},
145+
title={When Audio Denoising Meets Spiking Neural Network},
146+
year={2024},
147+
volume={},
148+
number={},
149+
pages={1524-1527},
150+
doi={10.1109/CAI59869.2024.00275}}
151+
```
64152

65153
## License
66154

67-
All the code in this repository is released under the [MIT License](https://opensource.org/licenses/MIT), for more details see the [LICENSE](LICENSE) file.
68-
69-
70-
<!-- MARKDOWN LINKS & IMAGES -->
71-
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
72-
[contributors-shield]: https://img.shields.io/github/contributors/haoxiangsnr/spiking-fullsubnet.svg?style=for-the-badge
73-
[contributors-url]: https://github.com/haoxiangsnr/spiking-fullsubnet/graphs/contributors
74-
[forks-shield]: https://img.shields.io/github/forks/haoxiangsnr/spiking-fullsubnet.svg?style=for-the-badge
75-
[forks-url]: https://github.com/haoxiangsnr/spiking-fullsubnet/network/members
76-
[stars-shield]: https://img.shields.io/github/stars/haoxiangsnr/spiking-fullsubnet.svg?style=for-the-badge
77-
[stars-url]: https://github.com/haoxiangsnr/spiking-fullsubnet/stargazers
78-
[issues-shield]: https://img.shields.io/github/issues/haoxiangsnr/spiking-fullsubnet.svg?style=for-the-badge
79-
[issues-url]: https://github.com/haoxiangsnr/spiking-fullsubnet/issues
80-
[license-shield]: https://img.shields.io/github/license/haoxiangsnr/spiking-fullsubnet.svg?style=for-the-badge
81-
[license-url]: https://github.com/haoxiangsnr/spiking-fullsubnet/blob/master/LICENSE.txt
155+
This project is licensed under the [MIT License](LICENSE).

‎docs/source/getting_started/installation.md‎

Lines changed: 69 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,50 +3,95 @@
33
## Prerequisites
44

55
Spiking-FullSubNet is built on top of PyTorch and provides standard audio signal processing and deep learning tools.
6-
To install the PyTorch binaries, we recommend [Anaconda](https://www.anaconda.com/products/individual) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) as a Python distribution.
6+
7+
- **Python**: >= 3.10
8+
- **uv**: We recommend using [uv](https://docs.astral.sh/uv/) as the package manager for faster and more reliable dependency management.
79

810
## Installation
911

10-
1. First, create a Conda virtual environment with Python. In our project, `python=3.10` is tested.
12+
### Option 1: Using uv (Recommended)
13+
14+
[uv](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments and dependencies efficiently.
15+
16+
1. **Install uv** (if not already installed):
1117
```shell
12-
# Create a virtual environment named `spiking-fullsubnet`
13-
conda create --name spiking-fullsubnet python=3.10
18+
# On macOS/Linux
19+
curl -LsSf https://astral.sh/uv/install.sh | sh
1420

15-
# Activate the environment
16-
conda activate spiking-fullsubnet
21+
# Or using pip
22+
pip install uv
23+
```
24+
25+
2. **Clone the repository**:
26+
```shell
27+
git clone https://github.com/haoxiangsnr/spiking-fullsubnet.git
28+
cd spiking-fullsubnet
1729
```
18-
The following steps will assume you have activated the `spiking-fullsubnet` environment.
1930

20-
2. Install Conda dependencies. Some dependencies of Spiking-FullSubNet, e.g., PyTorch and Tensorboard, are recommended to be installed using Conda instead of PyPI. First, we install a CUDA-capable PyTorch. Although `pytorch=2.1.1` has been tested, you may also [use other versions](https://pytorch.org/get-started/previous-versions/):
31+
3. **Install PyTorch** (CUDA version):
2132
```shell
22-
# Install PyTorch
23-
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
33+
# Install PyTorch with CUDA support first
34+
uv pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu121
35+
```
2436

25-
# Install other Conda dependencies
26-
conda install tensorboard joblib matplotlib
37+
4. **Sync dependencies and install the project**:
38+
```shell
39+
# Install all dependencies (creates .venv automatically)
40+
uv sync
41+
42+
# Or with GPU support (includes onnxruntime-gpu)
43+
uv sync --extra gpu
2744
28-
# (Optional) If you have "mp3" format audio data in your dataset, install ffmpeg first.
29-
conda install ffmpeg -c conda-forge
45+
# Or with all optional dependencies (gpu, test, docs, build)
46+
uv sync --all-extras
3047
```
3148

32-
3. Install PyPI dependencies. Clone the repository and install PyPI dependencies via `pip -r requirements.txt`. Check `requirements.txt` for more details.
49+
This will:
50+
- Create a virtual environment in `.venv`
51+
- Install all dependencies from `uv.lock`
52+
- Install `audiozen` in editable mode
53+
54+
5. **Activate the environment** (optional, uv commands auto-detect):
3355
```shell
34-
git clone https://github.com/haoxiangsnr/spiking-fullsubnet.git
56+
source .venv/bin/activate
57+
```
3558

36-
cd spiking-fullsubnet
59+
### Option 2: Using Conda + pip
60+
61+
If you prefer Conda, you can still use the traditional approach:
3762

38-
pip install -r requirements.txt
63+
1. **Create a Conda environment**:
64+
```shell
65+
conda create --name spiking-fullsubnet python=3.10
66+
conda activate spiking-fullsubnet
3967
```
4068

41-
4. We integrated all the audio signal processing tools into a package named `audiozen`. We will install the `audiozen` package in editable mode. By installing in editable mode, we can call `audiozen` package in everywhere of code, e.g, in `recipes` and `tools` folders. In addition, we are able to modify the source code of `audiozen` package directly. Any changes to the original package would reflect directly in your conda environment.
69+
2. **Install PyTorch**:
4270
```shell
43-
pip install --editable . # or for short: pip install -e .
71+
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
4472
```
4573

46-
Ok, all installations have done. You may speed up the installation by the following tips.
74+
3. **Install the project**:
75+
```shell
76+
git clone https://github.com/haoxiangsnr/spiking-fullsubnet.git
77+
cd spiking-fullsubnet
78+
pip install -e .
79+
```
80+
81+
## Common uv Commands
82+
83+
```shell
84+
uv sync # Sync dependencies from lockfile
85+
uv sync --extra gpu # Include GPU dependencies
86+
uv sync --all-extras # Include all optional dependencies
87+
uv add <package> # Add a new dependency
88+
uv lock --upgrade # Upgrade all dependencies
89+
uv run <command> # Run a command in the virtual environment
90+
uv build # Build the package
91+
```
4792

4893
```{tip}
49-
- [Speed up your Conda installs with Mamba](https://pythonspeed.com/articles/faster-conda-install/)
50-
- Use the [THU Anaconda mirror site](https://mirrors.tuna.tsinghua.edu.cn/help/anaconda/) to speed up the Conda installation.
51-
- Use the [THU PyPi mirror site](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/) to speed up the PyPI installation.
94+
- uv is significantly faster (10~100x) than pip and handles dependency resolution more reliably.
95+
- The `uv.lock` file ensures reproducible installations across different machines.
96+
- Use `uv run python script.py` to run scripts without manually activating the environment.
5297
```

0 commit comments

Comments
 (0)