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

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_sources must be a whole number from 1 to --max-sources.
  • The trainer uses the train and val splits. Keep test for 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

RouteWhat it does
GET /api/healthReports server status and loaded model components.
GET /api/public-statsReturns aggregated evaluation benchmarks from evaluation/public_summary.json.
POST /api/analyzeMultipart upload in audio. Counts sources with MC-dropout uncertainty, tags sounds, and estimates speaker count.
POST /api/separateJSON {"job_id": "..."}. Separates eligible recordings into labelled WAV stems, a residual stem, and a ZIP bundle.
POST /api/predictLegacy 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.