Clean up repo: proper model card, drop Space-specific gradio_app/ contents

Moves the checkpoint and class_names.json to repo root, replaces the stub README with a full model card, and removes gradio_app/ (app.py, requirements.txt, examples) since that belonged to a Space, not a model repo. The Gradio demo has been replaced by a static info Space at joakes90/engine-sound-classifier.

README.md

@@ -1,3 +1,107 @@
 ---
 license: cc-by-sa-4.0
+pipeline_tag: audio-classification
+tags:
+  - audio-classification
+  - audio
+  - pytorch
+  - panns
+  - audioset
+  - engine-sound
 ---
+
+# Engine Sound Classifier (PANNs CNN14 fine-tune)
+
+A fine-tuned [PANNs CNN14](https://github.com/qiuqiangkong/audioset_tagging_cnn)
+(pretrained on AudioSet) that classifies short audio clips of running engines
+into one of 34 configurations — cylinder count, layout, and stroke type (e.g.
+`i4`, `v8_cross`, `single_two_stroke`, `2_rotor`).
+
+**Status: early, ambitious, not yet accurate.** This is a first published
+checkpoint, shared to show the approach and current state, warts included.
+Recording-level balanced accuracy is **~0.33** on held-out test data (random
+guessing over 34 classes is ~0.03).
+
+An informational demo Space (sample clips, performance breakdown) is at
+[joakes90/engine-sound-classifier](https://huggingface.co/spaces/joakes90/engine-sound-classifier).
+The training code, notebook, and full diagnostic write-up live at
+[github.com/joakes90/auto_sound_train](https://github.com/joakes90/auto_sound_train).
+
+## Files
+
+- `best_model_run_d_soft_weights.pth` — fine-tuned state dict (~325 MB), Run D
+  checkpoint (best balanced accuracy so far).
+- `class_names.json` — ordered list of the 34 class labels the output layer
+  corresponds to.
+
+## Model details
+
+- **Architecture:** CNN14 from PANNs, pretrained on AudioSet, with the final
+  `fc_audioset` layer replaced by a 34-way linear head and fine-tuned.
+- **Input:** mono audio, resampled to 32 kHz, in 2-second windows (matching
+  the training manifest's window length).
+- **Output:** softmax over 34 engine configurations. For clips longer than
+  2s, run overlapping windows (e.g. 1s hop) and average per-window
+  probabilities before taking the top class — this "recording-level" pooling
+  is consistently more accurate than scoring a single window.
+
+## Classes
+
+`2_rotor`, `h12`, `h2`, `h4`, `h6`, `i2_180`, `i2_180_two_stroke`, `i2_270`,
+`i2_360`, `i2_360_two_stroke`, `i3`, `i4`, `i4_crossplane`, `i4_diesel`,
+`i5`, `i5_diesel`, `i6`, `i6_diesel`, `single_four_stroke`,
+`single_two_stroke`, `v10_72`, `v12`, `v2_45`, `v2_90`, `v4`,
+`v4_two_stroke`, `v6_120`, `v6_60`, `v6_90_even`, `v8_cross`, `v8_diesel`,
+`v8_flat`, `v8_voodoo`, `vr6`
+
+## Performance
+
+| Run | Change | Balanced acc | Micro acc |
+|---|---|---|---|
+| A | baseline (no regularization) | — | 0.38 (overfit) |
+| B | + SpecAugment/noise/mixup | 0.297 | 0.311 (underfit) |
+| C | fixed SpecAugment time-mask scale | 0.323 | 0.343 |
+| D | + softened class weights (`counts^-0.5`) | **0.330** | **0.376** |
+
+This checkpoint is Run D. Cylinder-family accuracy (does it at least get the
+cylinder count right) is meaningfully higher than exact-class accuracy —
+most confusion is between siblings within the same engine family, not wild
+misfires. Known weak spots: engines with many cylinders (8/12) are confused
+with close siblings far more than 1–2 cylinder engines, and a couple of
+classes (`v12`, `2_rotor`) remain poorly calibrated. Full diagnosis in
+`FINDINGS.md` in the training repo.
+
+## Usage
+
+```python
+import json
+import torch
+from huggingface_hub import hf_hub_download
+from panns_inference import AudioTagging
+
+REPO_ID = "joakes90/engine_sound_cassifier"
+CHECKPOINT = "best_model_run_d_soft_weights.pth"
+
+class_names = json.load(
+    open(hf_hub_download(REPO_ID, "class_names.json"))
+)["class_names"]
+
+# Loads PANNs' pretrained AudioSet CNN14, then swaps in our fine-tuned head.
+at = AudioTagging(checkpoint_path=None, device="cpu")
+backbone = at.model.module if isinstance(at.model, torch.nn.DataParallel) else at.model
+backbone.fc_audioset = torch.nn.Linear(backbone.fc_audioset.in_features, len(class_names))
+
+state_dict = torch.load(hf_hub_download(REPO_ID, CHECKPOINT), map_location="cpu")
+backbone.load_state_dict(state_dict)
+backbone.eval()
+
+# waveform: mono float tensor at 32kHz, shape (num_windows, window_samples)
+with torch.inference_mode():
+    logits = backbone.fc_audioset(backbone(waveform)["embedding"])
+    probs = torch.softmax(logits, dim=1).mean(dim=0)
+    top_class = class_names[probs.argmax()]
+```
+
+## License
+
+CC BY-SA 4.0.

gradio_app/README.md

@@ -1,53 +0,0 @@
----
-title: Engine Sound Classifier
-emoji: 🔧
-colorFrom: blue
-colorTo: gray
-sdk: gradio
-sdk_version: 6.20.0
-app_file: app.py
-pinned: false
----
-
-# Engine Sound Classifier (early checkpoint)
-
-Fine-tuned [PANNs CNN14](https://github.com/qiuqiangkong/audioset_tagging_cnn)
-(pretrained on AudioSet) that classifies short engine-audio clips into one of
-34 configurations — cylinder count, layout, and stroke type (e.g. `i4`,
-`v8_cross`, `single_two_stroke`, `2_rotor`).
-
-This is a **first published checkpoint**, not a finished product. It's shared
-to show the approach and current state, warts included.
-
-## Current performance
-
-- Recording-level balanced accuracy: **~0.33** on held-out test data (random
-  guessing over 34 classes is ~0.03).
-- Cylinder-family accuracy (does it at least get the cylinder count right) is
-  meaningfully higher than exact-class accuracy — most confusion is between
-  siblings within the same engine family, not wild misfires.
-- Known weak spots: engines with many cylinders (8/12) are confused with
-  close siblings far more than 1–2 cylinder engines, which have more
-  distinctive, widely-spaced firing pulses. A couple of classes (`v12`,
-  `2_rotor`) remain poorly calibrated even after two rounds of fixes.
-
-The full diagnostic history — what was tried, what broke, and why — lives in
-`FINDINGS.md` in the training repo this Space was built from.
-
-## How predictions are made
-
-Audio is resampled to 32 kHz mono, split into overlapping 2-second windows
-(matching the training data's window length), and the model's per-window
-class probabilities are averaged before picking the top prediction. This
-"recording-level" pooling is consistently more accurate than scoring a single
-window.
-
-## Deploying this Space
-
-The fine-tuned checkpoint (`best_model_run_d_soft_weights.pth`, ~325 MB) is
-not committed here. Either:
-
-1. Add it to this Space's repo via `git lfs`, or
-2. Upload it to a separate Hugging Face **model** repo and set the `HF_MODEL_REPO`
-   (and optionally `HF_MODEL_FILENAME`) Space secret/variable — `app.py` will
-   fetch it with `huggingface_hub.hf_hub_download` at startup.

gradio_app/app.py

@@ -1,152 +0,0 @@
-"""
-Gradio demo for the PANNs CNN14 engine-sound classifier (34 engine
-configurations, e.g. i4, v8_cross, single_two_stroke).
-
-This is an early checkpoint (Run D: SpecAugment-fixed + softened class
-weights). Recording-level balanced accuracy is ~0.33 on the held-out test
-set -- well above the 1/34 ~= 0.03 random baseline, but far from solved.
-See the README on this Space for known failure modes before trusting a
-prediction.
-"""
-
-import json
-import os
-from pathlib import Path
-
-import gradio as gr
-import torch
-import torchaudio
-from panns_inference import AudioTagging
-
-APP_DIR = Path(__file__).parent
-SAMPLE_RATE = 32000
-WINDOW_SEC = 2.0  # matches the training manifest's window length
-HOP_SEC = 1.0  # 50% overlap keeps short clips from being a single window
-
-# Local file takes priority (e.g. copied alongside app.py, or git-lfs'd into
-# the Space). Falls back to a Hugging Face *model* repo so the Space repo
-# itself doesn't have to carry a 300+MB checkpoint in git.
-CHECKPOINT_FILENAME = "best_model_run_d_soft_weights.pth"
-HF_MODEL_REPO = os.environ.get("HF_MODEL_REPO")  # e.g. "username/engine-cnn14"
-HF_MODEL_FILENAME = os.environ.get("HF_MODEL_FILENAME", CHECKPOINT_FILENAME)
-
-device = "cuda" if torch.cuda.is_available() else "cpu"
-
-with open(APP_DIR / "class_names.json") as f:
-    CLASS_NAMES = json.load(f)["class_names"]
-
-
-def _resolve_checkpoint_path() -> str:
-    local_path = APP_DIR / CHECKPOINT_FILENAME
-    if local_path.exists():
-        return str(local_path)
-    if HF_MODEL_REPO:
-        from huggingface_hub import hf_hub_download
-
-        return hf_hub_download(repo_id=HF_MODEL_REPO, filename=HF_MODEL_FILENAME)
-    raise FileNotFoundError(
-        f"No checkpoint at {local_path} and HF_MODEL_REPO is not set. Either "
-        f"place {CHECKPOINT_FILENAME} next to app.py, or set HF_MODEL_REPO to "
-        "a Hugging Face model repo that holds it."
-    )
-
-
-def _load_model() -> torch.nn.Module:
-    # checkpoint_path=None lets panns_inference fetch/cache its own pretrained
-    # AudioSet weights -- this mirrors exactly how training started, then we
-    # overwrite the head and load our fine-tuned state on top.
-    at = AudioTagging(checkpoint_path=None, device=device)
-    # AudioTagging only wraps the model in DataParallel on CUDA, so on a
-    # CPU-only Space (the common free tier) `.module` would not exist.
-    backbone = at.model.module if isinstance(at.model, torch.nn.DataParallel) else at.model
-    backbone.fc_audioset = torch.nn.Linear(
-        in_features=backbone.fc_audioset.in_features, out_features=len(CLASS_NAMES)
-    )
-    state_dict = torch.load(_resolve_checkpoint_path(), map_location=device)
-    backbone.load_state_dict(state_dict)
-    backbone.to(device)
-    backbone.eval()
-    return backbone
-
-
-model = _load_model()
-
-
-def _load_waveform(path: str) -> torch.Tensor:
-    waveform, sr = torchaudio.load(path)
-    if waveform.shape[0] > 1:
-        waveform = waveform.mean(dim=0, keepdim=True)
-    if sr != SAMPLE_RATE:
-        waveform = torchaudio.functional.resample(waveform, sr, SAMPLE_RATE)
-    return waveform.squeeze(0)
-
-
-def _windows(waveform: torch.Tensor) -> torch.Tensor:
-    win = int(WINDOW_SEC * SAMPLE_RATE)
-    hop = int(HOP_SEC * SAMPLE_RATE)
-    if waveform.shape[-1] < win:
-        waveform = torch.nn.functional.pad(waveform, (0, win - waveform.shape[-1]))
-        return waveform.unsqueeze(0)
-    starts = list(range(0, waveform.shape[-1] - win + 1, hop))
-    if starts[-1] + win < waveform.shape[-1]:
-        starts.append(waveform.shape[-1] - win)
-    return torch.stack([waveform[s : s + win] for s in starts])
-
-
-@torch.inference_mode()
-def classify(audio_path: str):
-    if audio_path is None:
-        return None, "Upload or record a clip first."
-
-    waveform = _load_waveform(audio_path)
-    duration_sec = waveform.shape[-1] / SAMPLE_RATE
-    batch = _windows(waveform).to(device)
-
-    logits = model(batch)["embedding"]
-    logits = model.fc_audioset(logits)
-    # mean_prob pooling: bounded per window, so one loud/confident window
-    # can't dominate the recording-level call (see FINDINGS.md).
-    probs = torch.softmax(logits, dim=1).mean(dim=0)
-
-    top = torch.topk(probs, k=min(5, len(CLASS_NAMES)))
-    result = {CLASS_NAMES[i]: float(p) for p, i in zip(top.values, top.indices)}
-    details = (
-        f"{duration_sec:.1f}s clip -> {batch.shape[0]} overlapping "
-        f"{WINDOW_SEC:.0f}s window(s), averaged."
-    )
-    return result, details
-
-
-EXAMPLES_DIR = APP_DIR / "examples"
-examples = [str(p) for p in sorted(EXAMPLES_DIR.glob("*.wav"))]
-
-DESCRIPTION = """
-Fine-tuned PANNs CNN14 (pretrained on AudioSet), classifying short engine
-audio clips into one of 34 configurations (cylinder count/layout/stroke,
-e.g. `i4`, `v8_cross`, `single_two_stroke`, `2_rotor`).
-
-**Status: early, ambitious, not accurate.** Recording-level balanced
-accuracy is ~0.33 on held-out data (random guessing over 34 classes is
-~0.03). Cylinder-family-level accuracy (does it at least get the cylinder
-count right) is meaningfully higher. Known weak spots: engines with many
-cylinders (8/12) are confused with siblings far more than 1-2 cylinder
-engines; a few classes (`v12`, `2_rotor`) are still poorly calibrated.
-Full write-up of the diagnosis and next steps is in the project's
-`FINDINGS.md`.
-"""
-
-demo = gr.Interface(
-    fn=classify,
-    inputs=gr.Audio(type="filepath", label="Engine audio (upload or record)"),
-    outputs=[
-        gr.Label(num_top_classes=5, label="Predicted configuration"),
-        gr.Textbox(label="Details", interactive=False),
-    ],
-    examples=examples if examples else None,
-    cache_examples=False,
-    title="Engine Sound Classifier (early checkpoint)",
-    description=DESCRIPTION,
-)
-
-if __name__ == "__main__":
-    demo.launch()

gradio_app/examples/i2_360.wav

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:09928bcb73b6b8a35531d651e71b1a14bd0d80a4d7009fbe367075fb2f56909f
-size 512078

gradio_app/examples/single_two_stroke.wav

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:29ade754afe5e7358efba7deb28323018c19fd1f750a82d34fc35d7861677399
-size 512078

gradio_app/examples/v2_45.wav

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:909d6080bf8f94b78611e5fd46e9d9740a1c7b493ffe9e09593c068fb2af8015
-size 512078

gradio_app/requirements.txt

@@ -1,8 +0,0 @@
-gradio
-torch
-torchaudio
-panns_inference
-torchlibrosa
-matplotlib
-numpy
-huggingface_hub