@suaveplan/audio-fingerprint - Python-tier high-accuracy audio fingerprinting service (librosa chromagram + scipy 2D peak detection + constellation hashing + Jaccard matching), exposed as a FastAPI REST API, with a typed TypeScript HTTP client (PythonAudioService) for browser/Node consumers.

High-accuracy audio fingerprinting service. The package is dual-runtime: a Python FastAPI backend (src/fingerprint.py + src/api/app.py) implements chromagram-based Shazam-style fingerprinting on top of librosa and scipy, and a TypeScript HTTP client (src/client/python-audio-service.ts) exposes that service to browser and Node consumers. It is the high-accuracy backend behind the browser-tier @suaveplan/react-audio-fingerprint React surface.

Documentation tree

api — api/app.py wraps the AudioFingerprinter core into a FastAPI HTTP service. It is the network surface the TypeScript…
- app — api/app.py wraps the AudioFingerprinter core into a FastAPI HTTP service. It is the network surface the TypeScript…
client — PythonAudioService is the typed HTTP client TypeScript and browser callers use to talk to the Python-tier audio finge…
- python-audio-service — PythonAudioService is the typed HTTP client TypeScript and browser callers use to talk to the Python-tier audio finge…
fingerprint — The AudioFingerprinter class is the Python core of @suaveplan/audio-fingerprint. It implements the full Shazam-styl…

Install

# TypeScript client side
bun add @suaveplan/audio-fingerprint

# Python service side (creates the suaveplan-audio-fingerprint micromamba env)
cd packages/media/audio/audio-fingerprint
micromamba create -f environment.yml -y

Quick start

# Start the FastAPI service on port 8000
micromamba run -n suaveplan-audio-fingerprint \
  uvicorn src.api.app:app --host 0.0.0.0 --port 8000

import { PythonAudioService } from "@suaveplan/audio-fingerprint";

const client = new PythonAudioService({ baseUrl: "http://localhost:8000" });
const health = await client.healthCheck();
const fingerprint = await client.fingerprint({ file: someAudioFile });
const match = await client.match({
    query_file: clipFile,
    reference_file: corpusFile,
    min_matches: 20,
});

Architecture

The package is split into two runtimes that share the wire format documented in src/types/audio-fingerprint.types.ts:

Python tier — src/fingerprint.py implements the AudioFingerprinter class (chromagram extraction via librosa, 2D peak detection via scipy.ndimage.maximum_filter, constellation-map hashing, Jaccard matching with median time-offset estimation). src/api/app.py wraps it in a FastAPI service with GET /, POST /fingerprint, and POST /match endpoints, plus CORS for localhost:3000 and localhost:5173.
TypeScript tier — src/client/python-audio-service.ts is the typed HTTP client. It depends only on the platform fetch, FormData, and AbortController APIs and runs unchanged in browsers and modern Node runtimes.

Algorithm

Audio loading — mono downmix and resample to 22050 Hz (configurable).
STFT — n_fft=2048, hop_length=512 (configurable).
Chromagram — 12-bin pitch-class profile (configurable) via librosa.feature.chroma_stft.
Peak detection — 2D local maxima on the normalised chromagram using a (3, 5) neighbourhood maximum filter; peaks below peak_threshold are discarded.
Constellation map — each peak is paired with the next fan_value peaks in time-sorted order.
Hashing — each pair becomes a (hash(f1, f2, dt), t1, dt) tuple.
Matching — set intersection on hashes, Jaccard similarity for confidence, median per-hash time offset for alignment.

Modules

src/fingerprint.py — AudioFingerprinter core. Docs: src/fingerprint.md.
src/api/app.py — FastAPI service. Docs: src/api/app.md.
src/client/python-audio-service.ts — typed HTTP client. Docs: src/client/python-audio-service.md.
src/types/audio-fingerprint.types.ts — wire-format type definitions (re-exported from @suaveplan/audio-fingerprint/types).

Testing

# TypeScript bridge tests + 100/100/100/100 istanbul coverage
bunx turbo test:coverage --filter=@suaveplan/audio-fingerprint

# Python service tests + 100% line+branch pytest coverage
cd packages/media/audio/audio-fingerprint
micromamba run -n suaveplan-audio-fingerprint pytest

Both gates hard-fail below 100% coverage. The Python test suite is not currently wired into turbo; it must be invoked standalone via micromamba. See for the rationale and the proposed follow-up to wire a turbo task once the broader Python tooling story lands.

5.4 KiB Raw Blame History