How utkarsharma7/hackenza_2026 works
Purpose and execution surface
This is a Python batch ML pipeline for classifying Arabic speakers as Native or Non-Native from audio. Its primary run path is:
scripts/load_data.py → scripts/extract_embeddings.py → scripts/train_classifier_compare.py → scripts/compare_models_on_test.py.
A separate final prediction path writes submission-style results through scripts/final_testing_on_test.py.
Input acquisition and audio preparation
scripts/load_data.py consumes URL-and-label records from manifests/input_data.csv, downloads audio, converts it to 16 kHz mono, and creates overlapping 10-second chunks. The boundary between external audio sources and local ML artifacts is captured by manifests/processed_manifest.csv; chunk files are generated outside the tracked tree under data/processed_audio_chunks/.
Representation extraction
scripts/extract_embeddings.py transforms chunked audio into fixed-size .npy feature vectors. It uses the Hugging Face Transformer model facebook/wav2vec2-lv-60-espeak-cv-ft, combines temporal Wav2Vec2 statistics with pitch features, normalizes vectors, and emits embedding metadata in manifests/final_training_manifest.csv plus the schema dimension in manifests/embedding_dim.txt.
scripts/extract_embeddings_for_CNN.py is a distinct representation path for sequence-preserving CNN inputs, tracked by manifests/embedding_dim_cnn.txt.
Model definitions and training
scripts/model.py centralizes PyTorch classifier architectures, including the baseline MLP and attention-equipped variant. scripts/train_classifier_compare.py loads embedding manifests, performs speaker-aware train/validation splitting, trains MLP, attention MLP, and LightGBM candidates, and chooses an operating threshold by validation F1. Trained artifacts are expected under an untracked models/ directory; its decision threshold is an essential inference contract.
Evaluation and prediction
scripts/compare_models_on_test.py evaluates trained candidate models against test data and reports classification metrics across thresholds. scripts/final_testing_on_test.py produces persisted final predictions at manifests/final_preds.csv; test-oriented inputs/manifests include manifests/test_data.csv and manifests/final_test.csv. scripts/make_predictions.py is the likely standalone inference entry point for applying trained artifacts.
CNN alternative branch
The repository also supports an alternative 1D-CNN experiment path: scripts/extract_embeddings_for_CNN.py prepares sequential embeddings, scripts/train1DCNN.py trains the CNN, and scripts/compare_cnn_on_test.py evaluates it. Its dataset contract is separated in manifests/cnn_training_manifest.csv, avoiding accidental interchange with pooled-vector MLP/LightGBM inputs.
Runtime and external dependencies
The runtime is Python 3.8+ with PyTorch, Transformers, librosa/scipy/torchaudio, scikit-learn, and LightGBM, declared in requirements.txt. CUDA is optional but material for Wav2Vec2 extraction and training. External services are source audio URLs and Hugging Face model download/cache infrastructure; the README also references a deployed Hugging Face Space, but deployment code is not present in this tree.
Main entry points: extract_embeddings.py Extract pooled embeddings · extract_embeddings_for_CNN.py Extract sequential embeddings · test_data.csv Test manifests · load_data.py Load and chunk audio
Components 22
Audio ingestion
- Source audio URLs · Remote audio and associated labels.
- Input records
manifests/input_data.csv - Load and chunk audio · Downloads, converts to 16 kHz mono, and creates overlapping chunks.
scripts/load_data.py - Processed manifest · Boundary for local chunked-audio artifacts.
manifests/processed_manifest.csv - Processed audio chunks · Untracked 10-second audio chunks.
Pooled-vector pipeline
- Wav2Vec2 model cache · facebook/wav2vec2-lv-60-espeak-cv-ft download/cache.
- Extract pooled embeddings · Combines Wav2Vec2 temporal statistics and pitch into normalized vectors.
scripts/extract_embeddings.py - Vector training manifest
manifests/final_training_manifest.csv - Vector schema dimension
manifests/embedding_dim.txt - Classifier architectures · Baseline and attention-equipped MLP definitions.
scripts/model.py - Train and select models · Speaker-aware split; compares MLP, attention MLP, and LightGBM using validation F1.
scripts/train_classifier_compare.py - Trained models and threshold · Untracked models plus the selected inference threshold.
CNN experiment branch
- Extract sequential embeddings · Preserves embedding sequences for CNN experiments.
scripts/extract_embeddings_for_CNN.py - CNN training manifest · Separate contract for sequential CNN inputs.
manifests/cnn_training_manifest.csv - CNN schema dimension
manifests/embedding_dim_cnn.txt - Train 1D CNN
scripts/train1DCNN.py
Evaluation and inference
- Test manifests · Test-oriented input and final test records.
manifests/test_data.csv - Evaluate candidate models · Reports test classification metrics across thresholds.
scripts/compare_models_on_test.py - Evaluate CNN
scripts/compare_cnn_on_test.py - Standalone inference · Applies trained artifacts to prediction inputs.
scripts/make_predictions.py - Produce final predictions
scripts/final_testing_on_test.py - Final predictions · Persisted submission-style results.
manifests/final_preds.csv
Connections 29
- Source audio URLs → Load and chunk audio: downloads
- Input records → Load and chunk audio: URLs and labels
- Load and chunk audio → Processed audio chunks: converts and chunks
- Load and chunk audio → Processed manifest: records chunks
- Processed manifest → Extract pooled embeddings: chunk metadata
- Processed audio chunks → Extract pooled embeddings: audio
- Wav2Vec2 model cache → Extract pooled embeddings: feature model
- Extract pooled embeddings → Vector training manifest: vector metadata
- Extract pooled embeddings → Vector schema dimension: writes schema
- Vector training manifest → Train and select models: pooled vectors
- Vector schema dimension → Train and select models: input contract
- Classifier architectures → Train and select models: MLP variants
- Train and select models → Trained models and threshold: models and threshold
- Processed manifest → Extract sequential embeddings: chunk metadata
- Processed audio chunks → Extract sequential embeddings: audio
- Wav2Vec2 model cache → Extract sequential embeddings: feature model
- Extract sequential embeddings → CNN training manifest: sequence metadata
- Extract sequential embeddings → CNN schema dimension: writes schema
- CNN training manifest → Train 1D CNN: sequences
- Train 1D CNN → Trained models and threshold: CNN artifact
- Test manifests → Evaluate candidate models: test inputs
- Trained models and threshold → Evaluate candidate models: candidates and threshold
- Test manifests → Evaluate CNN: test inputs
- Trained models and threshold → Evaluate CNN: CNN artifact
- Test manifests → Standalone inference: prediction inputs
- Trained models and threshold → Standalone inference: inference contract
- Test manifests → Produce final predictions: final test inputs
- Trained models and threshold → Produce final predictions: selected model
- Produce final predictions → Final predictions: writes