bowdet 0.1.0__py3-none-any.whl

bowdet/__init__.py

@@ -0,0 +1,6 @@
+"""bowdet - Bow change detection for bowed string instruments"""
+
+from .detect import detect
+
+__version__ = "0.1.0"
+__all__ = ["detect"]

bowdet/detect.py

@@ -0,0 +1,197 @@
+"""
+bowdet - Bow change detection for bowed string instruments
+Main detection function
+"""
+
+import os
+from pathlib import Path
+
+import numpy as np
+import torch
+import librosa
+import soundfile as sf
+from scipy.signal import find_peaks
+from huggingface_hub import hf_hub_download
+
+
+# ========== Weight Download ==========
+
+HF_REPO_ID = "Haotian-Yuan/bowdet"
+
+
+def _get_weights_dir():
+    weights_dir = Path.home() / ".bowdet" / "weights"
+    weights_dir.mkdir(parents=True, exist_ok=True)
+    return weights_dir
+
+
+def _download_weight(filename):
+    weights_dir = _get_weights_dir()
+    weight_path = weights_dir / filename
+    if not weight_path.exists():
+        print(f"Downloading {filename} from Hugging Face Hub...")
+        hf_hub_download(
+            repo_id=HF_REPO_ID,
+            filename=filename,
+            local_dir=str(weights_dir),
+        )
+        print(f"Weights saved to {weight_path}")
+    return weight_path
+
+
+# ========== CNN Inference (parameters match training exactly) ==========
+
+CNN_SR         = 22050
+CNN_N_MELS     = 80
+CNN_HOP        = 220
+CNN_WIN        = 512
+CNN_N_FFT      = 512
+CNN_WIN_SEC    = 1.0
+CNN_STRIDE_SEC = 0.1
+
+
+def _infer_cnn(audio, model, threshold, min_dist):
+    win_samples    = int(CNN_WIN_SEC * CNN_SR)
+    stride_samples = int(CNN_STRIDE_SEC * CNN_SR)
+    times, probs   = [], []
+
+    model.eval()
+    with torch.no_grad():
+        start = 0
+        while start + win_samples <= len(audio):
+            chunk = audio[start: start + win_samples].astype(np.float32)
+
+            # Mel spectrogram — identical to training
+            mel = librosa.feature.melspectrogram(
+                y=chunk, sr=CNN_SR,
+                n_mels=CNN_N_MELS, n_fft=CNN_N_FFT,
+                hop_length=CNN_HOP, win_length=CNN_WIN
+            )
+            mel = librosa.power_to_db(mel, ref=np.max).astype(np.float32)
+            mel = (mel - mel.mean()) / (mel.std() + 1e-9)
+
+            x = torch.tensor(mel).unsqueeze(0).unsqueeze(0)  # [1, 1, 80, T]
+            prob = torch.sigmoid(model(x)).item()
+            times.append((start + win_samples / 2) / CNN_SR)
+            probs.append(prob)
+            start += stride_samples
+
+    times  = np.array(times)
+    probs  = np.array(probs)
+    min_dist_frames = max(1, int(min_dist / CNN_STRIDE_SEC))
+    peaks, _ = find_peaks(probs, height=threshold, distance=min_dist_frames)
+    return times[peaks].tolist()
+
+
+# ========== MERT Inference (parameters match training exactly) ==========
+
+MERT_SR         = 24000
+MERT_WIN_SEC    = 1.0
+MERT_STRIDE_SEC = 0.1
+
+
+def _infer_mert(audio, model, processor, threshold, min_dist):
+    win_samples    = int(MERT_WIN_SEC * MERT_SR)
+    stride_samples = int(MERT_STRIDE_SEC * MERT_SR)
+    times, probs   = [], []
+
+    model.eval()
+    with torch.no_grad():
+        start = 0
+        while start + win_samples <= len(audio):
+            chunk  = audio[start: start + win_samples].astype(np.float32)
+            inputs = processor(chunk, sampling_rate=MERT_SR, return_tensors="pt")
+            logit  = model(inputs["input_values"])
+            probs.append(torch.sigmoid(logit).item())
+            times.append((start + win_samples / 2) / MERT_SR)
+            start += stride_samples
+
+    times  = np.array(times)
+    probs  = np.array(probs)
+    min_dist_frames = max(1, int(min_dist / MERT_STRIDE_SEC))
+    peaks, _ = find_peaks(probs, height=threshold, distance=min_dist_frames)
+    return times[peaks].tolist()
+
+
+# ========== Public API ==========
+
+def detect(audio_path, model="mert", threshold=0.5, min_dist=0.35):
+    """
+    Detect bow changes in a bowed string instrument recording.
+
+    Parameters
+    ----------
+    audio_path : str
+        Path to audio file (wav recommended).
+    model : str, default="mert"
+        Model to use: "mert" (more accurate, IoU@0.1 F1=0.616) or
+        "cnn" (faster, IoU@0.1 F1=0.554).
+    threshold : float, default=0.5
+        Peak detection threshold (0-1).
+        Lower values detect more bow changes but may increase false positives.
+    min_dist : float, default=0.35
+        Minimum time between bow changes in seconds.
+        Decrease for fast passages (e.g. spiccato): min_dist=0.2
+        Increase for slow passages (e.g. long bows): min_dist=0.5
+
+    Returns
+    -------
+    list of float
+        Timestamps of detected bow changes in seconds.
+
+    Examples
+    --------
+    >>> from bowdet import detect
+    >>> bow_changes = detect("recording.wav")
+    >>> print(bow_changes)
+    [1.23, 2.45, 3.67, ...]
+
+    >>> # Use CNN model (faster, less accurate)
+    >>> bow_changes = detect("recording.wav", model="cnn")
+
+    >>> # Custom parameters for fast spiccato passages
+    >>> bow_changes = detect("recording.wav", threshold=0.4, min_dist=0.2)
+    """
+    if not os.path.exists(audio_path):
+        raise FileNotFoundError(f"Audio file not found: {audio_path}")
+
+    if model == "cnn":
+        from .model_cnn import BowCNN
+
+        weight_path = _download_weight("BowDET-C.pth")
+        cnn = BowCNN()
+        ckpt = torch.load(str(weight_path), map_location="cpu", weights_only=False)
+        cnn.load_state_dict(ckpt["model_state_dict"])
+        cnn.eval()
+
+        audio, sr = sf.read(audio_path)
+        if audio.ndim > 1:
+            audio = audio.mean(axis=1)
+        if sr != CNN_SR:
+            audio = librosa.resample(audio, orig_sr=sr, target_sr=CNN_SR)
+
+        return _infer_cnn(audio, cnn, threshold, min_dist)
+
+    elif model == "mert":
+        from .model_mert import MERTClassifier
+        from transformers import AutoProcessor
+
+        weight_path = _download_weight("BowDET-M.pth")
+        processor = AutoProcessor.from_pretrained(
+            "m-a-p/MERT-v1-95M", trust_remote_code=True
+        )
+        mert = MERTClassifier()
+        ckpt = torch.load(str(weight_path), map_location="cpu", weights_only=False)
+        mert.load_state_dict(ckpt["model_state_dict"])
+        mert.eval()
+
+        audio, sr = sf.read(audio_path)
+        if audio.ndim > 1:
+            audio = audio.mean(axis=1)
+        if sr != MERT_SR:
+            audio = librosa.resample(audio, orig_sr=sr, target_sr=MERT_SR)
+
+        return _infer_mert(audio, mert, processor, threshold, min_dist)
+
+    else:
+        raise ValueError(f"Unknown model '{model}'. Choose 'mert' or 'cnn'.")

bowdet/model_cnn.py

@@ -0,0 +1,36 @@
+"""CNN model for bow change detection"""
+
+import torch
+import torch.nn as nn
+
+
+class BowCNN(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.features = nn.Sequential(
+            nn.Conv2d(1, 16, 3, padding=1),
+            nn.BatchNorm2d(16),
+            nn.ReLU(),
+            nn.Conv2d(16, 32, 3, padding=1),
+            nn.BatchNorm2d(32),
+            nn.ReLU(),
+            nn.MaxPool2d(2, 2),
+            nn.Conv2d(32, 64, 3, padding=1),
+            nn.BatchNorm2d(64),
+            nn.ReLU(),
+            nn.MaxPool2d(2, 2),
+            nn.Conv2d(64, 64, 3, padding=1),
+            nn.BatchNorm2d(64),
+            nn.ReLU(),
+            nn.AdaptiveAvgPool2d(1),
+        )
+        self.classifier = nn.Sequential(
+            nn.Flatten(),
+            nn.Linear(64, 64),
+            nn.ReLU(),
+            nn.Dropout(0.5),
+            nn.Linear(64, 1),
+        )
+
+    def forward(self, x):
+        return self.classifier(self.features(x)).squeeze(1)

bowdet/model_mert.py

@@ -0,0 +1,27 @@
+"""MERT-based model for bow change detection"""
+
+import torch
+import torch.nn as nn
+from transformers import AutoModel
+
+
+class MERTClassifier(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.mert = AutoModel.from_pretrained(
+            "m-a-p/MERT-v1-95M", trust_remote_code=True
+        )
+        self.classifier = nn.Sequential(
+            nn.Linear(768, 256),
+            nn.ReLU(),
+            nn.Dropout(0.3),
+            nn.Linear(256, 64),
+            nn.ReLU(),
+            nn.Dropout(0.3),
+            nn.Linear(64, 1),
+        )
+
+    def forward(self, input_values):
+        outputs = self.mert(input_values, output_hidden_states=False)
+        hidden = outputs.last_hidden_state.mean(dim=1)
+        return self.classifier(hidden).squeeze(1)

bowdet-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: bowdet
+Version: 0.1.0
+Summary: Bow change detection for bowed string instruments
+Home-page: https://github.com/haotian-yuan/bowdet
+Author: Haotian Yuan
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=1.13.0
+Requires-Dist: torchaudio>=0.13.0
+Requires-Dist: transformers>=4.30.0
+Requires-Dist: huggingface-hub>=0.16.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# bowdet
+
+**Bow change detection for bowed string instruments**
+
+bowdet detects bow changes in audio recordings of bowed string instruments (viola, violin, cello) using deep learning.
+
+## Installation
+
+```bash
+pip install bowdet
+```
+
+## Quick Start
+
+```python
+from bowdet import detect
+
+# Detect bow changes (returns list of timestamps in seconds)
+bow_changes = detect("recording.wav")
+print(bow_changes)  # [1.23, 2.45, 3.67, ...]
+```
+
+## Models
+
+| Model | IoU@0.1 F1 | Speed | Size |
+|-------|-----------|-------|------|
+| MERT (default) | 0.616 | ~2 min/min audio | 378 MB |
+| CNN | 0.554 | ~30 sec/min audio | 5 MB |
+
+## Parameters
+
+```python
+detect(
+    audio_path,           # path to wav file
+    model="mert",         # "mert" or "cnn"
+    threshold=0.5,        # peak detection threshold (0-1)
+    min_dist=0.35,        # minimum distance between bow changes (seconds)
+                          # decrease for fast passages (e.g. spiccato): min_dist=0.2
+                          # increase for slow passages (e.g. long bows): min_dist=0.5
+)
+```
+
+## Weights
+
+Weights are downloaded automatically on first use (~380 MB for MERT).
+Cached at `~/.bowdet/weights/`
+
+## Limitations
+
+- Trained on 9 performers across diverse repertoire (Bach, Biber, Penderecki, Hindemith, etc.)
+- Performance may degrade on playing styles significantly different from training data
+- Evaluated on viola recordings; expected to generalize to violin and cello
+- Designed for solo string instrument recordings; accompaniment or ensemble recordings may reduce accuracy
+
+## Citation
+
+[paper pending]
+
+## License
+
+MIT

bowdet-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+bowdet/__init__.py,sha256=A8XnAkWdRshEdu20sXpAPgiTAin17kdgFsxoEZewusY,137
+bowdet/detect.py,sha256=tZV-_pxcRO9ryUjbfjvYhmaL5FeF-0Qw-4QmBEqZ4TE,6264
+bowdet/model_cnn.py,sha256=lE8rHxoO8vGIOhfge-1s95rXo6tS1HCNKpIi1Gw3JOg,981
+bowdet/model_mert.py,sha256=vtgvKEuElR2Xca_kD76BXABYbb-r12xfpy5BC26HLu0,781
+bowdet-0.1.0.dist-info/METADATA,sha256=gGQIl-sgDaIln5GdwO2j8FC9rWshTXYh3t1qXRts6qA,2759
+bowdet-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bowdet-0.1.0.dist-info/top_level.txt,sha256=mADqg52I_9JN6B8dkhXwrxA0oswmGeuYBVfsNjxQgLE,7
+bowdet-0.1.0.dist-info/RECORD,,

bowdet-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bowdet-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bowdet