Populate Streamlit Space

.gitattributes

@@ -0,0 +1,38 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+models/*.pkl filter=lfs diff=lfs merge=lfs -text
+reports/*.png filter=lfs diff=lfs merge=lfs -text
+data/**/*.wav filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.cache/
+.numba_cache/
+.matplotlib_cache/
+.mpl-cache/
+.DS_Store
+uploads/
+.tmp/

README.md

@@ -0,0 +1,150 @@
+---
+title: Mic-ID
+emoji: "🎙️"
+colorFrom: red
+colorTo: purple
+sdk: streamlit
+sdk_version: "1.31.1"
+python_version: "3.10"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Mic-ID
+
+![Streamlit](https://img.shields.io/badge/Streamlit-FF4B4B?style=flat&logo=streamlit&logoColor=white) ![Python](https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white)
+
+A Streamlit front-end around a microphone fingerprinting baseline: drop in a short clip, get the most likely capture device plus an optional tonal hint. 🎙️ Built for quick lab demos, perfect for showing off how far classic features still go.
+
+## Table of Contents
+- [Highlights](#highlights)
+- [Live Demo Flow](#live-demo-flow)
+- [Quick Start](#quick-start)
+- [Controls at a Glance](#controls-at-a-glance)
+- [Device Recognition](#device-recognition)
+- [Scale Detection](#scale-detection)
+- [Bundled Example Clips](#bundled-example-clips)
+- [Download Contents](#download-contents)
+- [Testing](#testing)
+- [Project Layout](#project-layout)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+
+## Highlights
+- 🔎 End-to-end workflow for collecting, training, and demoing mic classification in one repo.
+- 🎛️ Feature-first approach: log-mel, MFCC, and spectral stats feed a histogram gradient boosting model.
+- 🧠 Friendly predictions: class IDs map to real device names so you can narrate results without decoding labels.
+- 🗂️ Lightweight artefacts: plain `.wav` folders in `data/`, pickled models in `models/`, metrics and confusion heatmaps in `reports/`.
+- ⚙️ Streamlit UI mirrors the CLI helpers, including loudness normalisation and experimental scale read-outs.
+
+## Live Demo Flow
+If you are running a live session, keep this script handy:
+
+- 🎧 `streamlit run app.py` from the project root.
+- 📂 Use `data/audio/airport-helsinki-204-6138-a.wav` to introduce the core upload flow and the default top-3 guess list.
+- 🔄 Swap to `data/audio/airport-helsinki-204-6138-b.wav` or `data/audio/airport-helsinki-204-6138-c.wav` to highlight how the twin scene shifts the predicted device while the environment stays constant.
+- 📱 Jump to `data/iphone/clip_05.wav` to show the locally recorded class and talk about adding in-house gear with `utils.py`.
+- 📊 Mention the probability bar chart and the saved copy under `uploads/hooks - <filename>` for later analysis.
+
+## Quick Start
+⚡ Four commands set everything up:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python train.py  # optional if you want to refresh the model
+```
+
+Then launch the app with `streamlit run app.py` (defaults to http://localhost:8501).
+
+## Hugging Face Space Setup
+Want a hosted demo? This repo is ready to drop into a Hugging Face Space using the Streamlit SDK. The short version:
+
+1. `pip install -U "huggingface_hub[cli]"` and run `huggingface-cli login` with a write-scoped access token.
+2. `git clone` your Space (for example `https://huggingface.co/spaces/connaaa/mic-id`) into an empty folder.
+3. Copy the contents of this repository into that clone, keeping `README.md`, `app.py`, `requirements.txt`, `packages.txt`, `models/`, and the curated `data/` subsets you want online.
+4. Commit and `git push`. The Space will build the dependencies listed in `requirements.txt` plus Debian packages from `packages.txt`.
+
+Large training corpora can be trimmed before pushing if you only need the pretrained model for inference.
+
+## Controls at a Glance
+| Control | Default | What it does |
+| --- | --- | --- |
+| File uploader | – | Accepts WAV/MP3/M4A, converts to 16 kHz mono, and normalises loudness before scoring. |
+| `How many guesses should we list?` slider | 3 | Sets the length of the ranked prediction list and bar chart. |
+| Training data expander | Collapsed | Recaps which datasets went into the current checkpoint, handy during demos. |
+| Prediction pane | Auto | Shows the tonal estimate (if any), RMS loudness, ranked devices, and probability chart. |
+
+Each control includes inline help text so presenters can improvise without notes.
+
+## Device Recognition
+- 🧱 Audio flows through `features.extract_features`, stitching log-mel and MFCC statistics with zero-crossing, centroid, roll-off, and flatness cues.
+- 🌲 `train.py` fits a `HistGradientBoostingClassifier`, stratified split, and saves artefacts to `models/model.pkl` plus the label encoder.
+- 📈 Every training run exports `reports/metrics.json` and `reports/confusion_matrix.png` so you can cite precision/recall live.
+- 🏷️ The app and CLI surface friendly names (e.g. “Zoom F8 field recorder”) pulled from `devices.describe_label()` to keep the story human-readable.
+
+## Scale Detection
+- 🎼 Uses a simple `librosa` chroma profile match across all major/minor keys.
+- ✅ High confidence (≥ 0.6) renders a green highlight, 0.4–0.6 shows an amber “low confidence” tag, and anything lower hides the scale suggestion entirely.
+- 🥁 Purely percussive or noisy clips skip the tonal hint, which is exactly what you want for location recordings.
+
+## Bundled Example Clips
+All sample audio lives under `data/` and mirrors the device IDs referenced in the demo.
+
+| Folder | What it represents | Count* |
+| --- | --- | --- |
+| `audio/` | TAU Urban Acoustic Scenes clips (device A) – Zoom F8 field recorder | 3 · demo bundle |
+| `audio2/` | TAU Urban Acoustic Scenes clips (device B) – Samsung Galaxy S7 | 2 · demo bundle |
+| `audio9/` | TAU Urban Acoustic Scenes clips (device C) – iPhone SE | 1 · demo bundle |
+| `iphone/` | Locally recorded iPhone speech snippets captured with `utils.py` | 2 |
+| `laptop/` | MacBook built-in mic samples recorded in a treated room | 2 |
+| `outtakes/` | Extra captures you can promote into training data after curation | 3 · demo bundle |
+
+⋆The Space ships with a travel-sized sample set; pull the full dataset locally if you want to retrain the checkpoint.
+
+## Download Contents
+Every run generates artefacts you can drop into a slide deck or share with collaborators:
+
+- 🎯 `models/model.pkl` and `models/label_encoder.pkl` store the trained classifier and label map.
+- 📊 `reports/metrics.json` plus `reports/confusion_matrix.png` capture evaluation snapshots for the latest training session.
+- 📁 Uploaded clips are preserved under `uploads/hooks - <original-name>` so you can replay or re-label them later.
+
+## Testing
+Quick smoke checks live in the scripts themselves:
+
+```bash
+# Rebuild the model and metrics
+python train.py
+
+# Score a few clips and verify probabilities look sane
+python predict.py data/laptop/clip_01.wav data/iphone/clip_05.wav --topk 5
+```
+
+For deeper regression coverage, wire these commands into your CI and compare the resulting metrics JSON against previous baselines.
+
+## Project Layout
+```
+mic-id/
+ ├─ app.py              # Streamlit UI for uploading and scoring clips
+ ├─ predict.py          # CLI scorer with friendly device names
+ ├─ train.py            # Dataset loader, model trainer, metric exporter
+ ├─ features.py         # Audio feature extraction helpers
+ ├─ utils.py            # Command-line recorder for new device samples
+ ├─ data/               # Per-device waveforms (TAU + local recordings)
+ ├─ models/             # Saved classifier + label encoder
+ ├─ reports/            # Metrics JSON and confusion matrix plots
+ ├─ docs/               # Data sourcing guide and prep notes
+ ├─ scripts/            # Dataset preparation helpers (TAU, Freesound, etc.)
+ └─ uploads/            # Cached demo uploads saved by the Streamlit app
+```
+
+## Roadmap
+- 🛰️ Add a lightweight CNN baseline alongside the gradient boosting model for comparison.
+- 🧪 Ship augmentation scripts (noise, EQ, impulse responses) to spotlight microphone colouration differences.
+- 🔐 Bundle provenance metadata (`data/metadata.csv`) and automated integrity checks for new clips.
+- 📦 Polish export helpers so the app can bundle probabilities + features in one download.
+
+## Contributing
+Issues and pull requests are welcome. 🤝 If you contribute new devices, include a short note (or a `metadata.csv` entry) describing the capture setup so others can reproduce your results and audit licensing.

app.py

@@ -0,0 +1,187 @@
+import io
+import os
+import tempfile
+import joblib
+import numpy as np
+import pandas as pd
+import streamlit as st
+import librosa
+import librosa.display
+import matplotlib.pyplot as plt
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+CACHE_ROOT = BASE_DIR / ".cache"
+NUMBA_CACHE_DIR = CACHE_ROOT / "numba"
+MPL_CACHE_DIR = CACHE_ROOT / "matplotlib"
+for cache_dir in (NUMBA_CACHE_DIR, MPL_CACHE_DIR):
+    cache_dir.mkdir(parents=True, exist_ok=True)
+os.environ.setdefault("NUMBA_CACHE_DIR", str(NUMBA_CACHE_DIR))
+os.environ.setdefault("MPLCONFIGDIR", str(MPL_CACHE_DIR))
+
+from features import extract_features
+from devices import describe_label
+
+
+NOTE_NAMES = [
+    "C",
+    "C#",
+    "D",
+    "D#",
+    "E",
+    "F",
+    "F#",
+    "G",
+    "G#",
+    "A",
+    "A#",
+    "B",
+]
+MAJOR_PROFILE = np.array([6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88])
+MINOR_PROFILE = np.array([6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17])
+UPLOAD_DIR = BASE_DIR / "uploads"
+MODEL_PATH = BASE_DIR / "models" / "model.pkl"
+ENCODER_PATH = BASE_DIR / "models" / "label_encoder.pkl"
+UPLOAD_DIR.mkdir(exist_ok=True)
+
+
+def estimate_scale(y: np.ndarray, sr: int) -> str | None:
+    """Return a rough musical scale (e.g., 'C major') or None if unclear."""
+
+    if y.size == 0:
+        return None
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+    if chroma.size == 0:
+        return None
+    chroma_mean = chroma.mean(axis=1)
+    norm = np.linalg.norm(chroma_mean, ord=1)
+    if norm == 0:
+        return None
+    chroma_mean = chroma_mean / norm
+
+    major_scores = [float(np.dot(chroma_mean, np.roll(MAJOR_PROFILE, i))) for i in range(12)]
+    minor_scores = [float(np.dot(chroma_mean, np.roll(MINOR_PROFILE, i))) for i in range(12)]
+
+    best_major = int(np.argmax(major_scores))
+    best_minor = int(np.argmax(minor_scores))
+    best_major_score = major_scores[best_major]
+    best_minor_score = minor_scores[best_minor]
+    best_score = max(best_major_score, best_minor_score)
+
+    # Require a minimal tonal structure to avoid spurious guesses on noise.
+    if best_score < 0.3:
+        return None
+
+    if best_major_score >= best_minor_score:
+        return f"{NOTE_NAMES[best_major]} major"
+    return f"{NOTE_NAMES[best_minor]} minor"
+
+st.set_page_config(page_title="Mic-ID (MVP)", layout="centered")
+st.title("Mic-ID (MVP)")
+st.caption("Upload ~5s audio → guess the recording device (demo)")
+
+with st.expander("Training data & devices", expanded=False):
+    st.markdown(
+        """
+        - **TAU Urban Acoustic Scenes 2019 Mobile**: 295 parallel scenes where the same moment was captured on three devices – Zoom F8 (device A, clips ending in `-a`), Samsung Galaxy S7 (device B, `-b`), and iPhone SE (device C, `-c`). We only keep folders containing a full `-a/-b/-c` triplet, so each mic has 295 clips.
+        - **Local additions**: 4 laptop and 4 iPhone recordings collected with `utils.py` to anchor the classifier on in-house gear.
+        - **Features & model**: log-mel + MFCC statistics flow into a histogram-based gradient boosting classifier tuned for this small balanced set.
+
+        Want more coverage? Record new clips under `data/<device>/` or export outtakes with `scripts/export_outtakes.py` before retraining via `python train.py`.
+        """
+    )
+
+
+@st.cache_resource
+def load_model():
+    try:
+        clf = joblib.load(MODEL_PATH)
+        le = joblib.load(ENCODER_PATH)
+        return clf, le
+    except Exception as exc:
+        st.warning(f"Could not load trained artefacts: {exc}")
+        return None, None
+
+
+clf, le = load_model()
+topk = None
+if clf and le is not None:
+    max_classes = max(1, len(le.classes_))
+    default_topk = min(3, max_classes)
+    topk = st.slider(
+        "How many guesses should we list?",
+        min_value=1,
+        max_value=max_classes,
+        value=default_topk,
+        help="Slide right to show more of the lower-confidence device guesses.",
+    )
+    st.caption("The slider above only changes how many ranked predictions you see.")
+
+file = st.file_uploader("Upload WAV/MP3/M4A", type=["wav","mp3","m4a"])
+
+if file and clf and le is not None:
+    data = file.read()
+    original_name = Path(file.name or "upload").name
+    renamed_name = f"hooks - {original_name}"
+    saved_path = UPLOAD_DIR / renamed_name
+    saved_path.write_bytes(data)
+    st.caption(f"Saved a copy as `{saved_path}`.")
+    try:
+        y, sr = librosa.load(io.BytesIO(data), sr=16000, mono=True)
+    except Exception:
+        suffix = os.path.splitext(file.name or "upload")[1] or ".wav"
+        with tempfile.NamedTemporaryFile(suffix=suffix) as tmp:
+            tmp.write(data)
+            tmp.flush()
+            y, sr = librosa.load(tmp.name, sr=16000, mono=True)
+    raw_y = y.copy()
+    rms = np.sqrt(np.mean(raw_y**2)) + 1e-8
+    scale = estimate_scale(raw_y, sr)
+    y = raw_y * (0.05 / rms)  # simple RMS norm
+    feats = extract_features(y, 16000).reshape(1, -1)
+    proba = clf.predict_proba(feats)[0]
+    idx = np.argsort(proba)[::-1]
+    st.subheader("Prediction")
+    if scale:
+        st.write(f"Estimated scale: **{scale}** (experimental)")
+    else:
+        st.write("Scale detection: the clip lacked clear musical content, so no scale estimate.")
+    st.write(f"Input loudness (RMS): {20 * np.log10(rms + 1e-12):.1f} dBFS")
+    limit = topk or 3
+    for i in idx[:limit]:
+        label = le.classes_[i]
+        st.write(f"{describe_label(label)} — **{proba[i] * 100:.1f}%**")
+    friendly_index = [describe_label(label) for label in le.classes_]
+    st.bar_chart(pd.Series(proba, index=friendly_index))
+
+    with st.expander("How the model listens", expanded=False):
+        st.markdown(
+            "We tidy the audio (level it, pull out key frequencies) and let the classifier score that summary. These charts show the raw waveform and the energy heatmap the model uses to decide." 
+        )
+
+        duration = raw_y.size / sr if raw_y.size else 0
+        times = np.linspace(0.0, duration, num=raw_y.size, endpoint=False) if raw_y.size else np.array([])
+
+        fig_wave, ax_wave = plt.subplots(figsize=(6, 2))
+        if raw_y.size:
+            ax_wave.plot(times, raw_y, linewidth=0.8, color="#1f77b4")
+            ax_wave.set_xlim(0, max(times) if raw_y.size else 0)
+        ax_wave.set_title("Waveform (time vs amplitude)")
+        ax_wave.set_xlabel("Time (s)")
+        ax_wave.set_ylabel("Amplitude")
+        ax_wave.grid(alpha=0.2)
+        st.pyplot(fig_wave, use_container_width=True)
+        plt.close(fig_wave)
+
+        mel = librosa.feature.melspectrogram(y=raw_y, sr=sr, n_fft=2048, hop_length=512, n_mels=64)
+        mel_db = librosa.power_to_db(mel, ref=np.max) if mel.size else mel
+        fig_spec, ax_spec = plt.subplots(figsize=(6, 3))
+        if mel.size:
+            img = librosa.display.specshow(mel_db, sr=sr, hop_length=512, x_axis="time", y_axis="mel", ax=ax_spec)
+            cbar = fig_spec.colorbar(img, ax=ax_spec, format="%+2.f dB")
+            cbar.set_label("Energy (dB)")
+        ax_spec.set_title("Log-mel spectrogram (what the model summarises)")
+        st.pyplot(fig_spec, use_container_width=True)
+        plt.close(fig_spec)
+elif file and not clf:
+    st.warning("No trained model found. Run `python train.py` first.")

data/audio/airport-helsinki-204-6138-a.wav

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

data/audio/airport-lisbon-175-4700-a.wav

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

data/audio2/bus-stockholm-35-1041-a.wav

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

data/audio2/bus-stockholm-35-1041-b.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9eb1bf29c4055d9b7863f4395b59a177873c1fb00f6e16f026597643f1339742
+size 1323044

data/audio9/street_pedestrian-london-149-4500-c.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:42ce95e42426e18ae1f25174147bfa799644a3064dcad7072b744239cef134af
+size 1323044

data/iphone/clip_01.wav

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

data/iphone/clip_05.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:017691167b2b7e93fe52ce7e643ca76767986c478e4efe4c2a66bbbfaee2c99a
+size 191832

data/laptop/clip_01.wav

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

data/laptop/clip_05.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:56d5a2ca715e1dc1f08f02d619c1a1c770ea60378b721638f9f2aeffb4829233
+size 160044

data/outtakes/manifest.csv

@@ -0,0 +1,13 @@
+filename,mic_suffix,friendly_name,description,source_path
+street_pedestrian-prague-203-5268-a.wav,a,Zoom F8 field recorder,TAU device A,data/audio9/street_pedestrian-prague-203-5268-a.wav
+street_pedestrian-prague-203-5268-c.wav,c,iPhone SE,TAU device C,data/audio9/street_pedestrian-prague-203-5268-c.wav
+street_pedestrian-prague-203-5268-b.wav,b,Samsung Galaxy S7,TAU device B,data/audio9/street_pedestrian-prague-203-5268-b.wav
+metro-paris-50-1524-a.wav,a,Zoom F8 field recorder,TAU device A,data/audio2/metro-paris-50-1524-a.wav
+metro-paris-50-1524-c.wav,c,iPhone SE,TAU device C,data/audio2/metro-paris-50-1524-c.wav
+metro-paris-50-1524-b.wav,b,Samsung Galaxy S7,TAU device B,data/audio2/metro-paris-50-1524-b.wav
+airport-london-205-6195-b.wav,b,Samsung Galaxy S7,TAU device B,data/audio/airport-london-205-6195-b.wav
+airport-london-205-6195-c.wav,c,iPhone SE,TAU device C,data/audio/airport-london-205-6195-c.wav
+airport-london-205-6195-a.wav,a,Zoom F8 field recorder,TAU device A,data/audio/airport-london-205-6195-a.wav
+airport-lisbon-175-5340-b.wav,b,Samsung Galaxy S7,TAU device B,data/audio/airport-lisbon-175-5340-b.wav
+airport-lisbon-175-5340-c.wav,c,iPhone SE,TAU device C,data/audio/airport-lisbon-175-5340-c.wav
+airport-lisbon-175-5340-a.wav,a,Zoom F8 field recorder,TAU device A,data/audio/airport-lisbon-175-5340-a.wav

data/outtakes/metro-paris-50-1524-a.wav

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

data/outtakes/metro-paris-50-1524-b.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1632c5c7a8d6a10d20ade4887bfd1544c96256c344da6e93e9d901dbea7830d5
+size 1323044

data/outtakes/metro-paris-50-1524-c.wav

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

devices.py

@@ -0,0 +1,12 @@
+MIC_FRIENDLY_NAMES = {
+    "audio": "Zoom F8 field recorder (TAU device A)",
+    "audio2": "Samsung Galaxy S7 (TAU device B)",
+    "audio9": "iPhone SE (TAU device C)",
+    "iphone": "Local iPhone recordings",
+    "laptop": "MacBook built-in microphone",
+}
+
+
+def describe_label(label: str) -> str:
+    """Return a human-readable microphone description for a raw label."""
+    return MIC_FRIENDLY_NAMES.get(label, label)

docs/data-sourcing.md

@@ -0,0 +1,65 @@
+# Data Sourcing Guide
+Mic-ID works best when every class corresponds to a capture device that has enough, diverse, and comparable recordings. The notes below list vetted public corpora and give you recipes for turning them into balanced training data without having to record long sessions yourself.
+
+## What to look for
+- **Parallel content**. Prefer datasets where the same scenes were captured on several devices so the label truly reflects the hardware, not the sound source.
+- **Consistent preprocessing**. Resample to 16 kHz mono, trim silence, and loudness-normalize (the repo utilities already normalise to ≈-26 dBFS).
+- **Usage rights**. Check every licence; most corpora below are CC BY or research-only.
+
+## Recommended open datasets
+### TAU Urban Acoustic Scenes 2019 Mobile (DCASE 2019 Task 1B)
+- **Why it helps**: Every 10 s clip was recorded in parallel across three devices: Zoom F8 (device A), Samsung Galaxy S7 (device B), and iPhone SE (device C). Treat the device ID as the label.
+- **Download**: Register at https://dcase.community/challenge2019/task-acoustic-scene-classification and grab the "TAU Urban Acoustic Scenes 2019 Mobile" archive (`TAU-urban-acoustic-scenes-2019-mobile-development.zip`).
+- **Command-line** (after approval/network access):
+  ```bash
+  mkdir -p data/raw && cd data/raw
+  wget https://zenodo.org/record/2589280/files/TAU-urban-acoustic-scenes-2019-mobile-development.zip
+  unzip TAU-urban-acoustic-scenes-2019-mobile-development.zip
+  ```
+- **Prep**: Parallel recordings are stored under `A/`, `B/`, `C/`. Run the provided helper to convert to 16 kHz mono (create this file if it doesn’t exist yet):
+  ```bash
+  python scripts/prepare_taus_mobile.py --input data/raw/TAU-urban-acoustic-scenes-2019-mobile-development --output data/taus_mobile
+  ```
+  (See the README below for how to organise `scripts/prepare_taus_mobile.py`.)
+- **Licence**: Creative Commons Attribution 4.0.
+
+### ASVspoof 2019 – Physical Access subset
+- **Why it helps**: Contains bona fide and replayed speech captured by 26 microphone / recorder pairs (high-quality mics plus several smartphones). Device identity is stored in the metadata (`rec_device`).
+- **Download**: Free for research. Create an account at https://www.asvspoof.org/ and request the 2019 PA subset.
+- **Command-line**:
+  ```bash
+  mkdir -p data/raw && cd data/raw
+  wget https://datashare.ed.ac.uk/download/handle/10283/3336/ASVspoof2019_PA_dev.zip
+  unzip ASVspoof2019_PA_dev.zip
+  ```
+  (Replace with the exact link you receive; ASVspoof frequently rotates URLs.)
+- **Prep**: Use the protocol files `ASVspoof2019_PA_cm_protocols` to map each wav to its `rec_device`. You can pivot those IDs into the folder names Mic-ID expects:
+  ```bash
+  python scripts/split_by_device.py --metadata data/raw/asvspoof2019/ASVspoof2019_PA_dev_cm_protocols/cm_protocols/PA_dev_cm.txt --audio-root data/raw/asvspoof2019/ASVspoof2019_PA_dev/ASVspoof2019_PA_dev --output-root data/asvspoof_devices
+  ```
+- **Licence**: Research-only; check that your use case complies.
+
+### Freesound + gear metadata
+- **Why it helps**: Many Freesound uploads include `gear` or `recording_device` tags such as "iphone_se" or "zoom_h4n". You can scrape curated lists rather than recording yourself.
+- **Download**: Requires a (free) Freesound API key.
+- **Command-line**:
+  ```bash
+  export FREESOUND_API_KEY=...
+  python scripts/freesound_pull.py --query "recording_device:iphone" --max-clips 200 --label iphone
+  python scripts/freesound_pull.py --query "recording_device:samsung" --max-clips 200 --label galaxy_s7
+  ```
+- **Prep**: The script should normalise file names and audio format to match `data/<device>/clip_xx.wav`. Keep a CSV with original URLs for attribution.
+- **Licence**: Clip-specific; many are CC BY or CC0. Honour attribution where required.
+
+## Balancing and augmentation tips
+- Aim for 60–100 clips per class before augmentation. Mix quiet/noisy scenes to avoid overfitting.
+- Apply simple augmentations (noise injection, EQ, impulse responses) per device to highlight microphone artefacts rather than content.
+- Track provenance in `data/metadata.csv` (`filename,device,source,licence`).
+- Keep a held-out validation split per device to spot leakage from near-duplicate clips.
+
+## Next steps
+1. Implement the helper scripts mentioned above under `scripts/`. Use `librosa`/`soundfile` so prep stays in Python.
+2. Store downloaded archives under `data/raw/` (ignored by git) and export processed clips to `data/<device>/`.
+3. Update `metadata.csv` whenever you add or remove external clips so the experiment log in `reports/` stays reproducible.
+
+For more ideas, browse the DCASE and ASVspoof challenge leaderboards—winning teams usually publish their data prep notes and often release additional impulse responses or parallel recordings.

features.py

@@ -0,0 +1,34 @@
+import numpy as np, librosa
+
+
+def load_mono(path, sr=16000):
+    x, sr = librosa.load(path, sr=sr, mono=True)
+    x, _ = librosa.effects.trim(x, top_db=30)
+    rms = np.sqrt(np.mean(x**2)) + 1e-8
+    x = x * (0.05 / rms)  # simple RMS target ≈ loudness norm
+    return x, sr
+
+
+def extract_features(x, sr=16000, n_mels=64, n_mfcc=20):
+    S = librosa.feature.melspectrogram(y=x, sr=sr, n_mels=n_mels)
+    logmel = librosa.power_to_db(S + 1e-9)
+    logmel_stats = np.hstack([logmel.mean(axis=1), logmel.std(axis=1)])
+
+    mfcc = librosa.feature.mfcc(S=librosa.power_to_db(S + 1e-9), sr=sr, n_mfcc=n_mfcc)
+    frames = mfcc.shape[1]
+    width = min(9, frames if frames % 2 else frames - 1)
+    if width < 3:
+        d1 = np.zeros_like(mfcc)
+        d2 = np.zeros_like(mfcc)
+    else:
+        d1 = librosa.feature.delta(mfcc, width=width)
+        d2 = librosa.feature.delta(mfcc, width=width, order=2)
+    mfcc_stats = np.hstack([mfcc.mean(axis=1), mfcc.std(axis=1),
+                            d1.mean(axis=1), d1.std(axis=1),
+                            d2.mean(axis=1), d2.std(axis=1)])
+
+    zcr = librosa.feature.zero_crossing_rate(x).mean()
+    centroid = librosa.feature.spectral_centroid(y=x, sr=sr).mean()
+    rolloff = librosa.feature.spectral_rolloff(y=x, sr=sr).mean()
+    flatness = librosa.feature.spectral_flatness(y=x).mean()
+    return np.hstack([logmel_stats, mfcc_stats, [zcr, centroid, rolloff, flatness]])

models/label_encoder.pkl

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

models/model.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9bd34e60ea1f1851d23b6808d4d0ad6ca2a10968322b527dd01f32b4e8761e0b
+size 2006992

packages.txt

@@ -0,0 +1,2 @@
+libsndfile1
+ffmpeg

predict.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Quick CLI to score audio clips with the trained Mic-ID model."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import os
+from pathlib import Path
+
+import joblib
+import librosa
+import numpy as np
+
+BASE_DIR = Path(__file__).resolve().parent
+CACHE_ROOT = BASE_DIR / ".cache"
+NUMBA_CACHE_DIR = CACHE_ROOT / "numba"
+MPL_CACHE_DIR = CACHE_ROOT / "matplotlib"
+for path in (NUMBA_CACHE_DIR, MPL_CACHE_DIR):
+    path.mkdir(parents=True, exist_ok=True)
+os.environ.setdefault("NUMBA_CACHE_DIR", str(NUMBA_CACHE_DIR))
+os.environ.setdefault("MPLCONFIGDIR", str(MPL_CACHE_DIR))
+
+from features import extract_features
+from devices import describe_label
+
+MODEL_PATH = Path("models/model.pkl")
+ENCODER_PATH = Path("models/label_encoder.pkl")
+
+
+def load_model():
+    if not MODEL_PATH.exists() or not ENCODER_PATH.exists():
+        raise SystemExit("Trained artefacts not found. Run `python train.py` first.")
+    clf = joblib.load(MODEL_PATH)
+    le = joblib.load(ENCODER_PATH)
+    return clf, le
+
+
+def load_audio(path: Path, sr: int = 16000) -> tuple[np.ndarray, int]:
+    if path.suffix.lower() == ".wav":
+        y, sr = librosa.load(path, sr=sr, mono=True)
+        return y, sr
+    # fall back to BytesIO so we also support .mp3/.m4a just like the Streamlit app
+    with path.open("rb") as f:
+        data = io.BytesIO(f.read())
+    y, sr = librosa.load(data, sr=sr, mono=True)
+    return y, sr
+
+
+def normalise_audio(y: np.ndarray) -> np.ndarray:
+    rms = float(np.sqrt(np.mean(y**2)) + 1e-8)
+    return y * (0.05 / rms), rms
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Score WAV/MP3/M4A clips with the Mic-ID classifier.")
+    parser.add_argument("paths", nargs="+", type=Path, help="Audio files to score")
+    parser.add_argument("--topk", type=int, default=3, help="How many ranked predictions to show per file")
+    args = parser.parse_args()
+
+    clf, le = load_model()
+    topk = max(1, min(args.topk, len(le.classes_)))
+
+    for path in args.paths:
+        if not path.exists():
+            print(f"[!] Skipping missing file: {path}")
+            continue
+        try:
+            y, sr = load_audio(path)
+        except Exception as exc:  # pragma: no cover - friendly CLI message
+            print(f"[!] Failed to load {path}: {exc}")
+            continue
+        y, rms = normalise_audio(y)
+        feats = extract_features(y, sr).reshape(1, -1)
+        proba = clf.predict_proba(feats)[0]
+        order = np.argsort(proba)[::-1]
+        print(f"\nFile: {path}")
+        print(f"RMS loudness: {20 * np.log10(rms + 1e-12):.1f} dBFS")
+        for rank, idx in enumerate(order[:topk], start=1):
+            label = le.classes_[idx]
+            friendly = describe_label(label)
+            print(f"  {rank}. {friendly} — {proba[idx] * 100:.1f}%")
+
+
+if __name__ == "__main__":
+    main()

reports/metrics.json

@@ -0,0 +1,45 @@
+{
+  "audio": {
+    "precision": 0.9726027397260274,
+    "recall": 0.9594594594594594,
+    "f1-score": 0.9659863945578231,
+    "support": 74.0
+  },
+  "audio2": {
+    "precision": 0.9864864864864865,
+    "recall": 0.9864864864864865,
+    "f1-score": 0.9864864864864865,
+    "support": 74.0
+  },
+  "audio9": {
+    "precision": 0.9605263157894737,
+    "recall": 0.9864864864864865,
+    "f1-score": 0.9733333333333334,
+    "support": 74.0
+  },
+  "iphone": {
+    "precision": 1.0,
+    "recall": 0.75,
+    "f1-score": 0.8571428571428571,
+    "support": 4.0
+  },
+  "laptop": {
+    "precision": 0.6666666666666666,
+    "recall": 0.6666666666666666,
+    "f1-score": 0.6666666666666666,
+    "support": 3.0
+  },
+  "accuracy": 0.9694323144104804,
+  "macro avg": {
+    "precision": 0.9172564417337309,
+    "recall": 0.8698198198198199,
+    "f1-score": 0.8899231476374334,
+    "support": 229.0
+  },
+  "weighted avg": {
+    "precision": 0.969657424053044,
+    "recall": 0.9694323144104804,
+    "f1-score": 0.969162582063393,
+    "support": 229.0
+  }
+}

requirements.txt

@@ -0,0 +1,9 @@
+streamlit
+librosa
+soundfile
+sounddevice
+scikit-learn
+numpy
+pandas
+matplotlib
+joblib

scripts/export_outtakes.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Copy a handful of parallel TAU Mobile clips into an outtakes folder for manual testing.
+
+Usage:
+    python scripts/export_outtakes.py --count 5 --output data/outtakes
+
+The script searches under the training `data/` tree for clip prefixes that include
+all three device suffixes (-a/-b/-c) and copies them (without removal) to the
+chosen output directory. Each exported clip retains its original file name and
+is accompanied by a `manifest.csv` describing the microphone mapping.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import random
+import shutil
+from collections import defaultdict
+from pathlib import Path
+
+MIC_SUFFIX_MAP = {
+    "a": ("Zoom F8 field recorder", "TAU device A"),
+    "b": ("Samsung Galaxy S7", "TAU device B"),
+    "c": ("iPhone SE", "TAU device C"),
+}
+
+
+def find_triplets(data_root: Path):
+    groups: dict[str, dict[str, Path]] = defaultdict(dict)
+    for wav_path in data_root.rglob("*.wav"):
+        name = wav_path.name
+        if len(name) < 6 or not name.endswith(".wav"):
+            continue
+        suffix = name[-5]
+        if suffix not in MIC_SUFFIX_MAP:
+            continue
+        prefix = name[:-6]
+        groups[prefix][suffix] = wav_path
+    # Keep only groups with all three devices
+    return {prefix: mapping for prefix, mapping in groups.items() if set(mapping) == set(MIC_SUFFIX_MAP)}
+
+
+def export_triplets(groups: dict[str, dict[str, Path]], output_dir: Path, count: int, seed: int | None) -> list[tuple[str, str, Path]]:
+    if not groups:
+        return []
+    rng = random.Random(seed)
+    prefixes = sorted(groups)
+    rng.shuffle(prefixes)
+    selected = prefixes[: min(count, len(prefixes))]
+    manifest_rows: list[tuple[str, str, Path]] = []
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for prefix in selected:
+        mapping = groups[prefix]
+        for suffix, path in mapping.items():
+            dest = output_dir / path.name
+            shutil.copy2(path, dest)
+            manifest_rows.append((dest.name, suffix, path))
+    return manifest_rows
+
+
+def write_manifest(rows: list[tuple[str, str, Path]], manifest_path: Path) -> None:
+    if not rows:
+        return
+    with manifest_path.open("w", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(["filename", "mic_suffix", "friendly_name", "description", "source_path"])
+        for filename, suffix, source in rows:
+            friendly, description = MIC_SUFFIX_MAP[suffix]
+            writer.writerow([filename, suffix, friendly, description, str(source)])
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Export a handful of TAU Mobile triplets for testing.")
+    parser.add_argument("--data-root", default="data", type=Path, help="Root directory containing per-device folders (default: data)")
+    parser.add_argument("--output", default="data/outtakes", type=Path, help="Where to copy the selected clips")
+    parser.add_argument("--count", type=int, default=5, help="Number of triplet prefixes to copy (default: 5)")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed for reproducibility")
+    args = parser.parse_args()
+
+    groups = find_triplets(args.data_root)
+    if not groups:
+        raise SystemExit("No complete triplets (-a/-b/-c) were found under the data root.")
+
+    rows = export_triplets(groups, args.output, args.count, args.seed)
+    if not rows:
+        raise SystemExit("Triplet export produced no files. Try lowering --count.")
+
+    write_manifest(rows, args.output / "manifest.csv")
+    print(f"Exported {len(rows)} wav files to {args.output} (covering {len(rows) // 3} triplets).")
+
+
+if __name__ == "__main__":
+    main()

train.py

@@ -0,0 +1,104 @@
+import os
+import glob
+import json
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+CACHE_ROOT = BASE_DIR / ".cache"
+NUMBA_CACHE_DIR = CACHE_ROOT / "numba"
+MPL_CACHE_DIR = CACHE_ROOT / "matplotlib"
+for path in (NUMBA_CACHE_DIR, MPL_CACHE_DIR):
+    path.mkdir(parents=True, exist_ok=True)
+os.environ.setdefault("NUMBA_CACHE_DIR", str(NUMBA_CACHE_DIR))
+os.environ.setdefault("MPLCONFIGDIR", str(MPL_CACHE_DIR))
+
+import numpy as np
+import matplotlib
+matplotlib.use("Agg", force=True)
+import matplotlib.pyplot as plt
+from sklearn.ensemble import HistGradientBoostingClassifier
+from sklearn.preprocessing import LabelEncoder
+from sklearn.metrics import classification_report, confusion_matrix
+from sklearn.model_selection import train_test_split
+import joblib
+
+from features import load_mono, extract_features
+
+DATA_DIR, MODEL_DIR, REPORT_DIR = "data", "models", "reports"
+os.makedirs(MODEL_DIR, exist_ok=True); os.makedirs(REPORT_DIR, exist_ok=True)
+
+IGNORED_DEVICES = {"outtakes"}
+SUFFIX_TO_DEVICE = {
+    "a": "audio",
+    "b": "audio2",
+    "c": "audio9",
+}
+TAU_DEVICE_DIRS = set(SUFFIX_TO_DEVICE.values())
+
+
+def resolve_device_label(device_dir: str, wav_path: str) -> str:
+    """Infer the correct device label for a wav file.
+
+    TAU scenes live under per-device directories but each folder still contains
+    the parallel `-a/-b/-c` recordings. Instead of trusting the directory name
+    (which mislabels the clips), derive the device from the filename suffix and
+    fall back to the directory label for any locally recorded additions that
+    do not follow that convention.
+    """
+
+    if device_dir in TAU_DEVICE_DIRS:
+        stem = Path(wav_path).stem
+        if "-" in stem:
+            _, suffix = stem.rsplit("-", 1)
+            if suffix in SUFFIX_TO_DEVICE:
+                return SUFFIX_TO_DEVICE[suffix]
+    return device_dir
+
+
+def load_dataset():
+    X, y = [], []
+    seen: set[tuple[str, str]] = set()
+    for device in sorted(
+        d for d in os.listdir(DATA_DIR)
+        if os.path.isdir(os.path.join(DATA_DIR, d))
+        and not d.startswith(".")
+        and d not in IGNORED_DEVICES
+    ):
+        for wav in glob.glob(os.path.join(DATA_DIR, device, "*.wav")):
+            label = resolve_device_label(device, wav)
+            key = (os.path.basename(wav), label)
+            if key in seen:
+                continue
+            seen.add(key)
+            x, sr = load_mono(wav); feats = extract_features(x, sr)
+            X.append(feats); y.append(label)
+    return np.array(X), np.array(y)
+
+
+if __name__ == "__main__":
+    X, y = load_dataset()
+    le = LabelEncoder(); y_enc = le.fit_transform(y)
+    Xtr, Xte, ytr, yte = train_test_split(X, y_enc, test_size=0.25, stratify=y_enc, random_state=42)
+
+    clf = HistGradientBoostingClassifier(max_depth=10, max_iter=400, learning_rate=0.08, random_state=42)
+    clf.fit(Xtr, ytr); yhat = clf.predict(Xte)
+
+    report = classification_report(yte, yhat, target_names=le.classes_, output_dict=True)
+    with open(os.path.join(REPORT_DIR, "metrics.json"), "w") as f: json.dump(report, f, indent=2)
+
+    cm = confusion_matrix(yte, yhat, normalize="true")
+    fig, ax = plt.subplots(figsize=(5,4)); im = ax.imshow(cm, cmap="Blues")
+    ax.set_xticks(range(len(le.classes_))); ax.set_xticklabels(le.classes_, rotation=45, ha="right")
+    ax.set_yticks(range(len(le.classes_))); ax.set_yticklabels(le.classes_)
+    for i in range(len(le.classes_)):
+        for j in range(len(le.classes_)):
+            ax.text(j, i, f"{cm[i,j]:.2f}", ha="center", va="center", fontsize=8)
+    ax.set_title("Confusion (normalized)"); fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04); fig.tight_layout()
+    fig.savefig(os.path.join(REPORT_DIR, "confusion_matrix.png"), dpi=160)
+
+    if hasattr(clf, "_feature_subsample_rng"):
+        clf._feature_subsample_rng = None
+
+    joblib.dump(clf, os.path.join(MODEL_DIR, "model.pkl"))
+    joblib.dump(le,  os.path.join(MODEL_DIR, "label_encoder.pkl"))
+    print("Saved model + reports.")

utils.py

@@ -0,0 +1,21 @@
+import os, argparse, numpy as np, sounddevice as sd, soundfile as sf, time
+
+
+def record_clips(device_name: str, count: int, seconds: float, sr: int = 16000):
+    outdir = os.path.join("data", device_name); os.makedirs(outdir, exist_ok=True)
+    print(f"Recording {count} clips x {seconds}s to {outdir} @ {sr}Hz. Ctrl-C to stop.")
+    try:
+        for i in range(1, count+1):
+            print(f"[{i}/{count}] Starts in 1s… speak normally."); time.sleep(1)
+            audio = sd.rec(int(seconds*sr), samplerate=sr, channels=1, dtype="float32"); sd.wait()
+            x = audio.squeeze(); rms = float(np.sqrt(np.mean(x**2)) + 1e-8); print(f"RMS {rms:.4f}")
+            sf.write(os.path.join(outdir, f"clip_{i:02d}.wav"), x, sr)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--device", required=True); ap.add_argument("--count", type=int, default=15)
+    ap.add_argument("--seconds", type=float, default=5.0)
+    args = ap.parse_args(); record_clips(args.device, args.count, args.seconds)