Annotation & Training

A classifier is only as good as the samples it learned from. This page covers the two things you control: how the labelled data is organised, and which of the two training routes you use to turn it into a model. Both routes end in a model file that Step 1 of the AI Classification wizard can load.

Choosing a training route

Step 2 — Train Model offers ML.NET (zero-code) and Python (deep learning) as two radio options. Start with ML.NET; move to Python only when you have both a lot of data and a reason to need a deeper model.

	ML.NET (zero-code)	Python (deep learning)
Prerequisites	None — built in	Python with PyTorch installed on the machine
Model type	Gradient-boosted trees on Mel features	Convolutional network or autoencoder, fully customisable
Output file	`model.zip`	`model.onnx`
Training time	Seconds to minutes	Minutes to hours
Data appetite	Works with tens of samples per class	Wants hundreds or more per class
Best for	A first working model, clearly separable fault types	Subtle differences, large archives, transfer from public models

Organising your training data

Both routes read the same layout: a root folder whose subfolder names are the class names. Put each recording in the folder of its class. That is the whole annotation format for whole-file classification — no separate label file to maintain.

data\
  OK\
    unit_0001.wav
    unit_0002.wav
    unit_0003.hdf
  Whine\
    unit_0104.wav
    unit_0117.wav
  Knock\
    unit_0233.wav
  Rub\
    unit_0301.wav

WAV and HEAD HDF files are both accepted and may be mixed in the same folder. Multi-channel files are mixed down to mono for feature extraction. Files that cannot be read are skipped and reported in the log rather than aborting the run.

The subfolder names become the class labels of the trained model, in alphabetical order. Use the exact names you want to see in results — and keep the same spelling when you later type them into the Class Labels field in Step 3.

Annotation projects

Beyond folder-based labelling, an annotation project stores labels as a portable JSON file that can be version-controlled and shared with colleagues. A project holds the class list plus, for each file, either a whole-file class label or a set of bounding boxes drawn on the spectrogram.

A bounding box marks a time-frequency region — start and end time in seconds, lower and upper frequency in Hz — and carries its own label, for example Order Resonance. This is what you use when the interesting event occupies only part of a long recording, or when several different events occur in one file and a single whole-file label would be misleading.

Annotation style	What it stores	Use when
Whole-file label	One class per recording	Short, homogeneous samples — the usual end-of-line case
Bounding box	Time span × frequency band, with a label	Long recordings, transient events, several events per file

Route A — built-in ML.NET trainer

Select ML.NET (zero-code), browse to the data folder, confirm the output path (model.zip is proposed inside the data folder), and press Start Training. Everything runs locally; no data is uploaded anywhere.

Under the hood each recording is reduced to a compact acoustic fingerprint: a 64-band Mel spectrogram is computed with a 1024-point FFT and 50 % overlap, and the mean and standard deviation of each Mel band across all frames become the feature vector. A gradient-boosted tree classifier is then trained on those vectors. This front end is deliberately robust — it cares about the spectral character of the sound and tolerates recordings of different lengths.

Route B — Python / PyTorch templates

Select Python (deep learning) to reveal the script settings. Two buttons write ready-to-run templates you can use unchanged or adapt:

Export CNN Template — a convolutional classifier over Mel spectrograms (64 Mel bands × 128 frames), exported to ONNX at the end of training with a dynamic batch dimension.
Export Autoencoder Template — an autoencoder for anomaly detection, trained on normal samples only, which also writes out its anomaly threshold.

Set the script path, the data folder, the output .onnx path and the number of Epochs (default 50), then press Start. The script is launched as a separate process and its console output is streamed live into the training log, so you can watch loss and accuracy per epoch and cancel if the run is not converging.

Your own scripts work too, as long as they accept the same command line:

python train.py --data <folder> --output <model.onnx> --epochs <N> --type <classifier|autoencoder>

Python and PyTorch are not installed with Deepsona. If the log reports a missing dependency, install the packages the template names (torch, torchaudio, onnx) into the Python environment you pointed at, then run again.

Reading the training log and metrics

The log records the whole run: how many files were found and in which classes, how many yielded usable features, the progress of training, and a final summary. The ML.NET route reports three figures:

Metric	Meaning	How to read it
Micro accuracy	Fraction of all samples classified correctly	Dominated by the largest class
Macro accuracy	Average of the per-class accuracies	Treats a rare class as equally important — the more honest number
Log-loss	Penalty for confident wrong answers	Lower is better; a rising log-loss with high accuracy means over-confidence

These metrics are measured on the data the model was trained with, so they are an upper bound, not a prediction of field performance. The number that matters is what you get by running Batch Classify over recordings that were never part of training. A large gap between the two is the classic sign of overfitting — usually cured with more and more varied samples.

How much data do you need?

Minimum to get moving — roughly 20–30 recordings per class for the ML.NET route, and a similar number held back for checking.
Comfortable — 100+ per class, spread over different units, shifts and operators, so the model learns the fault rather than the recording day.
Deep learning — several hundred to thousands per class, or start from a pre-trained Model Zoo model and adapt it.
Balance — keep class counts within roughly the same order of magnitude. If OK samples outnumber faults 100:1, trim the OK set or consider anomaly detection instead.
Variety within a class — ten recordings of ten different faulty units teach far more than a hundred recordings of one faulty unit.

From trained model to deployment

Load the resulting model in Step 1 — Load Model and check the reported signature.
Enter the class labels in Step 3 — Settings, in the order the folders were read (alphabetical).
Run a couple of known samples in Step 4 — Classify and confirm the per-class scores look sensible.
Run your held-back set through Step 5 — Batch Classify and export the CSV; this is the evidence you keep for the release record.
Archive the model file together with a note of the data set and settings used — a model without its provenance cannot be reproduced later.

Related: AI Acoustic Classification (overview) · ONNX Inference · Anomaly Detection