Skip to content

Commit e256dc7

Browse files
committed
Added timestamps and parameter support
1 parent b30b08e commit e256dc7

22 files changed

+716
-429
lines changed

.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,9 @@ results/
1919
.DS_Store
2020
Thumbs.db
2121
.idea/
22+
23+
# GitHub specific
24+
.github/
25+
26+
# Testing
27+
tests/

CITATION.cff

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,25 @@
11
cff-version: 1.2.0
2-
title: "MAPSS-measures: Perceptual Separation and Match Metrics"
2+
title: "MAPSS: Manifold-based Assessment of Perceptual Source Separation"
33
message: "If you use this software, please cite it as below."
44
authors:
5-
- family-names: "YourLastName"
6-
given-names: "YourFirstName"
7-
orcid: "https://orcid.org/0000-0000-0000-0000"
8-
version: "1.0.1"
9-
date-released: "2025-09-12"
5+
- family-names: "Ivry"
6+
given-names: "Amir"
7+
- family-names: "Cornell"
8+
given-names: "Samuele"
9+
- family-names: "Watanabe"
10+
given-names: "Shinji"
11+
version: "1.0.0"
12+
date-released: "2025-09-11"
13+
identifiers:
14+
- type: "arxiv"
15+
value: "2509.09212v1"
16+
- type: "doi"
17+
value: "10.48550/arXiv.2509.09212"
18+
keywords:
19+
- "source separation"
20+
- "perceptual metric"
21+
- "audio signal processing"
22+
- "self-supervised learning"
23+
- "manifold learning"
24+
homepage: "https://arxiv.org/abs/2509.09212v1"
25+
license: "CC-BY-4.0"
-3 Bytes
Binary file not shown.

Manifests/example_English.json

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[
2+
{
3+
"mixture_id": "female_pair_example",
4+
"references": [
5+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/orig/female_inst_sim_1.wav",
6+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/orig/female_inst_sim_2.wav"
7+
],
8+
"systems": {
9+
"Algo1_SASSEC": [
10+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/Algo1/female_inst_sim_1.wav",
11+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/Algo1/female_inst_sim_2.wav"
12+
]
13+
}
14+
},
15+
{
16+
"mixture_id": "male_pair_example",
17+
"references": [
18+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/orig/male_inst_sim_1.wav",
19+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/orig/male_inst_sim_2.wav"
20+
],
21+
"systems": {
22+
"Algo1_SASSEC": [
23+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/Algo1/male_inst_sim_1.wav",
24+
"C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC/Signals/Algo1/male_inst_sim_2.wav"
25+
]
26+
}
27+
}
28+
]

Manifests/example_English.py

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
from pathlib import Path
2+
3+
SASSEC_PATH = "C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC" # full path
4+
5+
MANIFEST = [
6+
{
7+
"mixture_id": "female_pair_example",
8+
"references": [
9+
Path(SASSEC_PATH) / Path("Signals/orig/female_inst_sim_1.wav"),
10+
Path(SASSEC_PATH) / Path("Signals/orig/female_inst_sim_2.wav"),
11+
],
12+
"systems": {
13+
"Algo1_SASSEC": [
14+
Path(SASSEC_PATH) / Path("Signals/Algo1/female_inst_sim_1.wav"),
15+
Path(SASSEC_PATH) / Path("Signals/Algo1/female_inst_sim_2.wav"),
16+
],
17+
"Algo2_SASSEC": [
18+
Path(SASSEC_PATH) / Path("Signals/Algo2/female_inst_sim_1.wav"),
19+
Path(SASSEC_PATH) / Path("Signals/Algo2/female_inst_sim_2.wav"),
20+
],
21+
},
22+
},
23+
{
24+
"mixture_id": "male_pair_example",
25+
"references": [
26+
Path(SASSEC_PATH) / Path("Signals/orig/male_inst_sim_1.wav"),
27+
Path(SASSEC_PATH) / Path("Signals/orig/male_inst_sim_2.wav"),
28+
],
29+
"systems": {
30+
"Algo1_SASSEC": [
31+
Path(SASSEC_PATH) / Path("Signals/Algo1/male_inst_sim_1.wav"),
32+
Path(SASSEC_PATH) / Path("Signals/Algo1/male_inst_sim_2.wav"),
33+
],
34+
},
35+
},
36+
]
Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,26 @@
66
{
77
"mixture_id": "female_pair_example",
88
"references": [
9-
Path(SASSEC_PATH) / Path("Signals/orig/female_inst_sim_1.wav"),
10-
Path(SASSEC_PATH) / Path("Signals/orig/female_inst_sim_2.wav"),
9+
Path(SASSEC_PATH) / Path("Signals/orig/female_inst_sim_3.wav"),
10+
Path(SASSEC_PATH) / Path("Signals/orig/female_inst_sim_4.wav"),
1111
],
1212
"systems": {
1313
"Algo1_SASSEC": [
14-
Path(SASSEC_PATH) / Path("Signals/Algo1/female_inst_sim_1.wav"),
15-
Path(SASSEC_PATH) / Path("Signals/Algo1/female_inst_sim_2.wav"),
14+
Path(SASSEC_PATH) / Path("Signals/Algo1/female_inst_sim_3.wav"),
15+
Path(SASSEC_PATH) / Path("Signals/Algo1/female_inst_sim_4.wav"),
1616
],
1717
},
1818
},
1919
{
2020
"mixture_id": "male_pair_example",
2121
"references": [
22-
Path(SASSEC_PATH) / Path("Signals/orig/male_inst_sim_1.wav"),
23-
Path(SASSEC_PATH) / Path("Signals/orig/male_inst_sim_2.wav"),
22+
Path(SASSEC_PATH) / Path("Signals/orig/male_inst_sim_3.wav"),
23+
Path(SASSEC_PATH) / Path("Signals/orig/male_inst_sim_4.wav"),
2424
],
2525
"systems": {
2626
"Algo1_SASSEC": [
27-
Path(SASSEC_PATH) / Path("Signals/Algo1/male_inst_sim_1.wav"),
28-
Path(SASSEC_PATH) / Path("Signals/Algo1/male_inst_sim_2.wav"),
27+
Path(SASSEC_PATH) / Path("Signals/Algo1/male_inst_sim_3.wav"),
28+
Path(SASSEC_PATH) / Path("Signals/Algo1/male_inst_sim_4.wav"),
2929
],
3030
},
3131
},

Manifests/example_music_drums.py

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
from pathlib import Path
2+
3+
SASSEC_PATH = "C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC" # full path
4+
5+
MANIFEST = [
6+
{
7+
"mixture_id": "female_pair_example",
8+
"references": [
9+
Path(SASSEC_PATH) / Path("Signals/orig/wdrums_inst_sim_1.wav"),
10+
Path(SASSEC_PATH) / Path("Signals/orig/wdrums_inst_sim_2.wav"),
11+
Path(SASSEC_PATH) / Path("Signals/orig/wdrums_inst_sim_3.wav"),
12+
],
13+
"systems": {
14+
"Algo1_SASSEC": [
15+
Path(SASSEC_PATH) / Path("Signals/Algo1/wdrums_inst_sim_1.wav"),
16+
Path(SASSEC_PATH) / Path("Signals/Algo1/wdrums_inst_sim_2.wav"),
17+
Path(SASSEC_PATH) / Path("Signals/Algo1/wdrums_inst_sim_3.wav"),
18+
],
19+
},
20+
},
21+
]
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
from pathlib import Path
2+
3+
SASSEC_PATH = "C:/postdoc/R1 - PS and PM/Data - speech separation MOS/SASSEC" # full path
4+
5+
MANIFEST = [
6+
{
7+
"mixture_id": "female_pair_example",
8+
"references": [
9+
Path(SASSEC_PATH) / Path("Signals/orig/nodrums_inst_sim_1.wav"),
10+
Path(SASSEC_PATH) / Path("Signals/orig/nodrums_inst_sim_2.wav"),
11+
Path(SASSEC_PATH) / Path("Signals/orig/nodrums_inst_sim_3.wav"),
12+
],
13+
"systems": {
14+
"Algo1_SASSEC": [
15+
Path(SASSEC_PATH) / Path("Signals/Algo1/nodrums_inst_sim_1.wav"),
16+
Path(SASSEC_PATH) / Path("Signals/Algo1/nodrums_inst_sim_2.wav"),
17+
Path(SASSEC_PATH) / Path("Signals/Algo1/nodrums_inst_sim_3.wav"),
18+
],
19+
},
20+
},
21+
]

README.md

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Both measures are implemented with diffusion maps over self-supervised embedding
1010

1111
## Installation
1212

13-
### Requirements
13+
### Congifuration
1414
- Python **3.11.x** (tested on 3.11.9)
1515
- `pip` (latest version recommended)
1616
- Optional: NVIDIA GPU with drivers supporting **CUDA ≥ 12.4** (tested with driver 12.6)
@@ -48,8 +48,7 @@ Both measures are implemented with diffusion maps over self-supervised embedding
4848
```
4949
- **GPU build (CUDA 12.4, works with driver 12.6):**
5050
```bash
51-
pip uninstall -y torch torchvision torchaudio
52-
pip install torch==2.6.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
51+
pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu124
5352
```
5453

5554
---
@@ -61,7 +60,7 @@ The system supports **JSON** or **Python** manifests to specify mixtures, refere
6160

6261
### Arguments
6362
- `--manifest` (required): Path to `.json` or `.py` manifest file
64-
- `--model` (required): Embedding model (`raw`, `wavlm`, `wav2vec2`, `hubert`, `wavlm_base`, `wav2vec2_base`, `hubert_base`, `wav2vec2_xlsr`, `ast`)
63+
- `--model` (required): Embedding model (`raw`, `wavlm`, `wav2vec2`, `hubert`, `wavlm_base`, `wav2vec2_base`, `hubert_base`, `wav2vec2_xlsr`)
6564
- `--layer` (optional): Model layer (validated against model-specific limits)
6665
- `--alpha` (optional): Diffusion map α parameter in `[0,1]` (default from config)
6766
- `--max-gpus` (optional): Limit GPUs used
@@ -124,6 +123,21 @@ Results and parameters are stored automatically in the `results/` directory.
124123

125124
---
126125

126+
## Citing
127+
128+
If you use this work, please cite:
129+
130+
```bibtex
131+
@article{Ivry2025MAPSS,
132+
title = {MAPSS: Manifold-based Assessment of Perceptual Source Separation},
133+
author = {Ivry, Amir and Cornell, Samuele and Watanabe, Shinji},
134+
journal = {arXiv preprint arXiv:2509.09212},
135+
year = {2025},
136+
url = {https://arxiv.org/abs/2509.09212}
137+
}
138+
139+
---
140+
127141
## License
128142
129143
This project is licensed under the **MIT License** — a short and permissive license that allows reuse, modification, and distribution with attribution.

TESTING.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# How to run the grid tests
2+
3+
## Quick start (from project root)
4+
5+
1. Create/activate your Python environment and install dependencies.
6+
2. Run the grid tests using the provided demo manifest and tiny audio assets:
7+
8+
```bash
9+
python -m tests.run_grid_tests --manifest tests/manifest_example.py
10+
```
11+
12+
This runs **all models** (including `raw`) at their **default layers** (see `argshield.MODEL_DEFAULT_LAYER`)
13+
and tries `--max-gpus 0 1 2` with `alpha=1.0`. It validates that:
14+
- the pipeline executes without crashing,
15+
- the generated CSVs are present,
16+
- and the PS/PM per-frame outputs are **non-empty** and **not constant**.
17+
18+
### Faster, subset runs
19+
20+
If you first want a quicker sanity check:
21+
22+
```bash
23+
python -m tests.run_grid_tests --subset raw wavlm_base --gpus 0
24+
```
25+
26+
## Running the main program manually
27+
28+
Example:
29+
30+
```bash
31+
python -m main --manifest tests/manifest_example.py --model wavlm --layer 24 --alpha 1.0 --max-gpus 1 --verbose
32+
```
33+
34+
## Notes
35+
36+
- The demo manifest and tiny WAV files live under `tests/`. They are short, low amplitude, and
37+
are sufficient to exercise masking, diffusion maps, and PS/PM metric computations.
38+
- The tests don't change any pipeline functionality. They only _run_ the code and check results.
39+
- The CLI "argument shielding" (validation/parsing) now lives in `argshield.py`. See
40+
`argshield._validate_gpus` for the explicit check that `--max-gpus` is an integer ≥ 0.

0 commit comments

Comments
 (0)