Spectrogram Matcher

A PySide6 GUI tool for interactively matching spectrograms. The tool:

• Loads spectrograms and their embeddings from an HDF5 file.
• Computes pairwise cosine distances between all spectrogram embeddings.
• Lets you pick a query spectrogram.
• Shows two proposal sets:
  1. 20 nearest neighbours (lowest cosine distance)
  2. 20 quantile-ranked examples from the query’s distance distribution
• Lets you label each proposal as Match or No match.
• Lets you save your annotations to a JSON file.

---

📦 Installation

1. Clone or download this repository:

git clone https://github.com/janclemenslab/spectrogram-matcher.git
cd spectrogram-matcher

2. Install dependencies:

conda create -n sm -y python=3.13 PySide6 numpy h5py matplotlib -c conda-forge

2. Download the data from this link and put it in the same folder as the file spectrogram_matcher.py.

▶️ Usage

Change into the directory with the spectrogram_matcher.py and embeddings.h5 file and run the application:

conda activate sm
python spectrogram_matcher.py \
  --annotator YOURNAME \
  [--quantile-bias 0.5] \
  [--quantile-max-distance 0.8] \
  [--all-nearest]

• --quantile-bias: bias exponent for quantile sampling. Use values < 1.0 to overrepresent close neighbours (e.g., 0.5 for log-like spacing). Use 1.0 for even spacing.
• --quantile-max-distance: upper bound on distance for proposals beyond the top-20 nearest neighbours. Only candidates with distance <= this value are considered for the quantile-sampled set.
• --all-nearest: instead of 20 nearest + 20 quantile-sampled proposals, selects the 40 nearest neighbours, ordered by distance to the query.

⌨️ Shortcuts

• Ctrl+S — Save results
• N — Next query
• R — Pick random query

---

Created with ChatGPT5