ASTW

ASTW is a small audio classification library that turns a folder of audio files and labels into a portable model artifact.

The full workflow is:

1. Pass it audios and labels.
2. Call fit.
3. save the result. You get a self-contained safetensors export with config.json, preprocessor_config.json, labels.json, metrics.json and a README.md ready to push to the Hugging Face Hub.
4. load that folder back, locally or directly from a HF repo id, and call predict.

ASTW stands for Audio Shapes The World. The library trains compact audio classifiers from scratch with a local log-mel frontend, so new models do not depend on Whisper weights or any external pretrained audio backbone.

Highlights

• Single high-level class: ASTW.
• Encoder-only Transformer over 80-bin log-mel features, with masked mean pooling by default and attentive statistics pooling as an option.
• Muon optimizer on matrix-shaped parameters and AdamW on the rest.
• SpecAugment, label smoothing, cosine LR with warmup, early stopping.
• Safetensors-first export, Hugging Face Hub compatible folder layout.
• CLI for one-shot prediction.

Installation

pip install astw

For local development:

python -m pip install -e .

To run the bundled examples:

python -m pip install -e '.[examples]'

Quick Start

Train from scratch on raw audios:

from astw import ASTW

audios = [
    "audio/cat_01.wav",
    "audio/cat_02.wav",
    "audio/dog_01.wav",
    "audio/dog_02.wav",
]
labels = ["cat", "cat", "dog", "dog"]

model = ASTW()
model.fit(audios, labels, epochs=8, batch_size=4)
model.save("exports/my-audio-model")

Load it back later, locally or from the Hub:

from astw import ASTW

local = ASTW.load("exports/my-audio-model")
print(local.predict("dog.wav"))

remote = ASTW.from_pretrained("your-user/your-audio-model")
print(remote.predict("clip.wav", top_k=3))

Architecture

The default model is a compact encoder-only audio classifier:

• local 80-bin log-mel frontend at 16 kHz (Whisper-style normalization, no external download)
• two-layer Conv1d stem with temporal stride-2 downsampling
• a stack of Transformer-style encoder blocks with multi-head self-attention and feed-forward layers
• attentive statistics pooling over valid frames (attention-weighted mean and standard deviation), available as pooling="attentive_stats", with masked mean pooling kept as the default
• linear classification head

The training recipe combines Muon for matrix-shaped parameters with AdamW for the rest, plus SpecAugment, cosine LR with warmup, label smoothing and macro-F1 early stopping.

You can switch the pooling policy when constructing the classifier:

ASTW(pooling="mean")             # default
ASTW(pooling="attentive_stats")

Saved Artifact Layout

save produces a folder with at least these files:

• model.safetensors
• config.json
• preprocessor_config.json
• labels.json
• metrics.json
• README.md

That folder can be uploaded to the Hugging Face Hub as-is and loaded with either ASTW.load(path) or ASTW.from_pretrained(repo_id).

Supported Audio Inputs

fit and predict accept any of:

• a file path
• a numpy array (use input_sample_rate= if it is not 16 kHz)
• a (array, sample_rate) tuple
• a dict with array and sample_rate

CLI

astw predict path/to/audio.wav --model exports/my-audio-model
astw predict path/to/audio.wav --model your-user/your-audio-model --top-k 5

Examples

Three runnable examples are shipped with the repository:

• examples/esc50_animals trains a 10-class animal classifier on the ESC-50 dataset
• examples/esc50_transport trains a 5-class transport classifier on the same dataset
• examples/speech_emotion trains a 4-class English speech emotion classifier on a focused RAVDESS subset (neutral, calm, angry, surprised) with a speaker-independent test split

Both follow the same 0_train.py and 1_test.py workflow and produce a confusion matrix and a metrics JSON.

Tests

A small smoke test suite lives in tests/test_smoke.py. Run it with:

python -m pip install pytest
pytest

Build A Wheel

python -m pip install build
python -m build

License

MIT. See LICENSE.