Docs
Set up, train, call the API and understand the limits.
Set up
Python 3.11 or 3.12 is recommended. From the project folder:
py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt python app.py
python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python app.py
Then open http://127.0.0.1:5000.
Dataset format
Create data/metadata.csv with one row per labelled mixture. Paths may be absolute or relative to the CSV.
mixture_path,num_sources,split audio/mix_0001.wav,2,train audio/mix_0002.wav,3,val audio/mix_0003.wav,4,test
num_sourcesmust be a whole number from 1 to--max-sources.- The trainer uses the
trainandvalsplits. Keeptestfor the final evaluation. - Split the original recordings before mixing, so the same stems never appear in both train and test.
Train and evaluate
python scripts/download_models.py python scripts/train.py all --full python scripts/evaluate.py --export-public
The best checkpoint by validation macro MAE is saved to checkpoints/source_count_clip.pt. Training uses one full eight-second mixture per label and leaves the test split out. Current status: checkpoint found.
API
| Route | What it does |
|---|---|
GET /api/health | Reports server status and loaded model components. |
GET /api/public-stats | Returns aggregated evaluation benchmarks from evaluation/public_summary.json. |
POST /api/analyze | Multipart upload in audio. Counts sources with MC-dropout uncertainty, tags sounds, and estimates speaker count. |
POST /api/separate | JSON {"job_id": "..."}. Separates eligible recordings into labelled WAV stems, a residual stem, and a ZIP bundle. |
POST /api/predict | Legacy count-only endpoint for single-file predictions. |
curl -X POST -F "audio=@example.wav" http://127.0.0.1:5000/api/analyze
Press the button to call the server.
Known limits & retention
- Without a trained checkpoint, analysis endpoints report that no trained model is loaded.
- One eight-second clip produces one count prediction. Long files are centre-cropped and short files are padded.
- Softmax confidence is not a guarantee of correctness; check the How it works page for held-out accuracy and unseen-speaker limits.
- Uploaded audio, stems, and ZIPs live in
uploads/jobs/and are deleted automatically after 30 minutes and on server startup.