SensorFusion2026/ELP-Gunshot-Detector

ML Gunshot Detector for Elephant Listening Project. African forest elephant conservation research though CSU Chico in collaboration with Cornell University and CU Bolder. # ELP Gunshot Detector A CNN-based detector for gunshot audio, built for the Elephant Listening Project (Cornell / CSU Chico / CU Boulder). Training runs locally or on the SDSC Expanse ACCESS GPU supercomputer. > **Python baseline:** Python 3.10 recommended for compatibility with Expanse (TensorFlow 2.15 container). > Dependencies are managed via `pyproject.toml`. --- ## Local Setup ### Create and activate environment ```bash python3.10 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -e .[full] ``` --- ## Environment Variables (.env) ```bash cp .env.example .env ``` Edit `.env`: ```bash ENVIRONMENT="local" CORNELL_DATA_ROOT="/path/to/ELP_Cornell_Data" ``` For remote (Expanse): ```bash ENVIRONMENT="remote" CORNELL_DATA_ROOT="None" ``` Note: CORNELL_DATA_ROOT not required for remote training --- ## Data Creation **Steps 1 and 3 create shared, version-controlled artifacts.** Do **NOT** re-run them unless the team agrees to change the dataset. ### Pipeline ``` create_clips_plan → cut_wav_clips → create_splits → create_tfrecords ``` ### Steps ```bash # 1. Clip plan (committed, do not re-run casually) python -m elp_gunshot.data_creation.create_clips_plan # 2. Cut clips python -m elp_gunshot.data_creation.cut_wav_clips # 3. Splits (committed, do not re-run casually) python -m elp_gunshot.data_creation.create_splits # 4. TFRecords python -m elp_gunshot.data_creation.create_tfrecords ``` #### TFRecords options Optional environment variables: - `MODEL`: `model1` | `model2` | `model3` (default: `model1`) - `MASK`: `nomask` | `bp _ ` (default: `nomask`) Bandpass frequency mask in Hz; `0 _ /{train,val,test}.tfrecord ``` Each TFRecord generation run also writes: ``` data/tfrecords/ _ /metadata.json ``` with train-split spectrogram normalization stats (`spec_norm_mean`, `spec_norm_std`) and preprocessing settings. --- ## Model Training via SDSC Expanse ```bash ssh @login.expanse.sdsc.edu ``` Refer to SDSC Expanse User G …