How yeyupiaoling/audioclassification-pytorch works
Project type and purpose
• This is an open-source audio classification system built on PyTorch.
• It provides end-to-end CLI-driven pipelines: data preparation, feature extraction, training, evaluation and inference.
• Core use cases: environment-sound classification, speaker verification, real-time audio recognition.
File-structure analysis
Top-level scripts (entry points)
• create_data.py ← raw-audio → train/test lists
• extract_features.py ← raw-audio → saved features
• train.py ← configs → model training
• eval.py ← trained model → metrics + confusion plots
• infer.py ← single audio → prediction
• infer_record.py ← streaming mic → continuous prediction
• record_audio.py ← record mic → raw wav files
Configuration
• configs/*.yml ← data augment, model, optimizer, scheduler, preprocess parameters
Core library package “macls/”
• data_utils/ ← Reader, Featurizer, CollateFn, DataLoader wrappers
• models/ ← Model definitions (EcapaTdnn, ResNetSE, etc.) + pooling layers + utils
• optimizer/ ← Scheduler, optimizer wrappers
• metric/ ← Accuracy, loss, confusion-matrix generation
• utils/ ← Checkpointing, argument parsing, logging, record I/O
• trainer.py ← High-level Trainer class orchestrating epochs, forward/backward, val/test
• predict.py ← Prediction utilities for batch inference
Docs & tooling
• docs/images/ ← sample outputs, confusion matrices
• tools/download_*.sh ← external data download
• requirements.txt, setup.py
README insights
• Config-driven: everything—from feature type to model architecture to optimizer—is controlled via YAML.
• Extensible models / pooling / preprocessors.
• VisualDL used for training logging and real-time monitoring.
Main components
A. Data Sources
• Raw audio datasets (e.g., UrbanSound8K, custom dialect datasets)
• Noise datasets for augmentation
B. Data Preparation
• create_data.py → generates train/test lists
C. Feature Extraction
• extract_features.py or on-the-fly via macls/data_utils/featurizer
• Feature store on disk (dataset/features/)
D. Training Pipeline
• train.py invokes macls/trainer.Trainer
• DataLoader (macls/data_utils) → batch of features/labels
• Model (macls/models) → forward pass
• Loss & Metric (macls/metric) → compute loss/accuracy
• Optimizer & Scheduler (macls/optimizer) → update weights
• Checkpointing (macls/utils/checkpoint) → save best model
• VisualDL server ← logs & scalars
E. Evaluation Pipeline
• eval.py → loads checkpoint → runs evaluation loop → outputs metrics & confusion images
F. Inference
• infer.py → single or batch audio → preprocess → model → label prediction
• infer_record.py + record_audio.py → real-time streaming inference
G. Configuration
• YAML files feed into all CLI scripts via unified argument parser
H. External Services/Tools
• VisualDL for dashboards
• HuggingFace models (optional) as preprocessors
• Shell scripts in tools/ for dataset download
Relationships and interactions
Raw Audio → Data Preparation → Feature Extraction → Training/Inference
Training → Model Artifacts → Evaluation & Inference
Configs → all pipelines (inject parameters)
• Trainer depends on DataUtils, Models, Optimizer, Metric, Utils
• Inference reuses DataUtils + Models + Utils
Architectural patterns & principles
• Modular separation by concern (data, models, training, utils)
• Config-driven orchestration (YAML + argparse)
• Plugin-style extensibility (drop-in new model in macls/models or new pooling in macls/models/pooling.py)
• Batch vs. streaming inference reuse core modules
Essential elements
• Clear labels per component (e.g., “Trainer”, “Featurizer”)
• Containers grouping “Data”, “Core Library”, “Scripts”, “Monitoring”