Build a “What’s This Track?” Button for a Music or DJ App

What you're building

The interaction is familiar: the user hears a track (in a club, in a stream, in your own player), taps a button, and a moment later sees exactly what it is and where to get it. Under the hood that is two API calls glued to a fingerprint: POST /v1/tracks/identify turns a few seconds of audio into a matched catalogue track, and GET /v1/tracks/links turns that track into a row of “Listen on” / “Buy on” buttons.

This guide wires the whole thing together for a desktop or DJ app, where you can bundle the fingerprinter and keep the work off the user's network. Identify is a paid-tier feature (a free-tier key gets a 403) and costs 10 credits per fingerprint, matched or not.

Architecture

The flow is four hops, all driven from your app's backend or main process:

• Capture a short audio clip: a file the user picks, or a few seconds recorded from the output.
• Fingerprint it with fpcalc (the Chromaprint CLI) into a compact integer array.
• Identify: post the fingerprint, read the ranked results.
• Hydrate & render: fetch full metadata and platform links for the best hit and draw the buttons.

A successful identify returns a deliberately slim body: a ranked list, best first, each with a confidence from 0 to 1:

{
  "matched": true,
  "results": [
    {
      "id": "8471023",
      "title": "Harder, Better, Faster, Stronger",
      "artists": [{ "id": 1925615, "name": "Daft Punk", "is_primary": true, "is_remixer": false }],
      "confidence": 0.86
    }
  ],
  "credits_charged": 10
}

import { execFile } from "node:child_process";
import { promisify } from "node:util";

const run = promisify(execFile);

// Runs in the Electron MAIN process. fpcalc is the Chromaprint CLI,
// bundled next to the app binary. -raw prints the integer fingerprint.
async function fingerprint(path: string): Promise<number[]> {
  const { stdout } = await run("fpcalc", ["-raw", path]);
  const m = stdout.match(/FINGERPRINT=(.+)/);
  if (!m) throw new Error("fpcalc produced no fingerprint");
  return m[1].split(",").map(Number);
}

const BASE = "https://api.sonovault.now/v1";
const headers = { "x-api-key": API_KEY };

// Still in the main process - the key never reaches the renderer.
async function identify(fp: number[]) {
  const res = await fetch(`${BASE}/tracks/identify`, {
    method: "POST",
    headers: { ...headers, "content-type": "application/json" },
    body: JSON.stringify({ fingerprint: fp }),
  });
  if (res.status === 503) throw new Error("matcher busy - retry shortly");
  const { matched, results } = await res.json();
  return matched ? results[0] : null;   // best hit, or null
}

// hit.id came from the identify result. Fetch metadata + links in parallel.
async function resolve(id: string) {
  const [track, linkRes] = await Promise.all([
    fetch(`${BASE}/tracks/${id}`, { headers }).then(r => r.json()),
    fetch(`${BASE}/tracks/links?id=${id}`, { headers }).then(r => r.json()),
  ]);

  // track.title, track.artists, track.isrc - linkRes.links: { source, url }[]
  for (const { source, url } of linkRes.links) {
    const verb = source === "beatport" ? "Buy on" : "Listen on";
    addButton(`${verb} ${source}`, url);
  }
  return track;
}

Going further

• Debounce the button.Fingerprinting and a round-trip take a beat; disable the button while a lookup is in flight so an impatient double-tap doesn't burn 20 credits on the same clip.
• Cache by fingerprint. If the same clip comes back (a user re-taps on the same track), you already know the answer, so key a small cache on a hash of the fingerprint and skip the call.
• Proxy through your backend. A shipped desktop app is not a safe place for an API key. Send the fingerprint to your server, add x-api-key there, and forward to Sonovault. Your key never leaves your infrastructure.
• No fpcalc? Upload instead.If a target can't run the binary, post the track to the same endpoint at 320 kbps and let the server fingerprint it (cost becomes 10 + ceil(MB)).