harmonic-mixing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Harmonic mixing and track analysis

Tempo, key and compatibility data from [Song Finder](https://songfinder.dev), a free online **song finder** and audio toolkit. No API key, no account, no header needed for any endpoint here.

## Everything is keyed by ISRC

Get one first:

```bash
curl -s "https://songfinder.dev/api/track/search?q=strobe+deadmau5"
```

Take `data[0].isrc` when the title matches; otherwise show the candidates and ask which one. If the user only has a link or a file, use the `identify-song` skill first.

## Tempo, key and audio features

```bash
curl -s "https://songfinder.dev/api/track/detail?isrc=USUS10800096"
```

```json
{ "track": { "title": "...", "artist": "...", "releaseYear": 2008 },
  "features": {
    "tempo": 127.981,
    "key": { "name": "B Minor", "camelot": "10A", "openKey": "1m",
             "compatible": ["10B", "9A", "11A"] },
    "energy": 0.62, "danceability": 0.55, "valence": 0.21,
    "acousticness": 0.02, "loudness": -9.4 },
  "tempoCrossCheck": 128.0,
  "genre": { "primary": "...", "styles": ["..."] } }
```

**Round the tempo when you report it.** `127.981` is a measurement; the user wants "128 BPM".

**`energy`, `danceability`, `valence`, `acousticness`, `instrumentalness`, `liveness` and `speechiness` are 0–1.** Report them as percentages. `valence` is musical positivity, not loudness — a 20% valence track sounds melancholy regardless of how hard it hits.

### Always check `tempoCrossCheck`

It is a second provider's reading. **If it differs from `features.tempo` by more than ~3 BPM, one of them is half- or double-time** — an 87/174 pair is the same groove counted differently. Say which is which rather than reporting one number as fact:

> 174 BPM (a second source reads 87 — same groove, counted half-time)

This matters enormously for beatmatching and is the single most common way tempo data misleads people.

### Missing data is normal

Long-tail and regional releases often have a tempo but no key, or no `features` block at all. Report what exists; do not present a gap as an error.

## The Camelot wheel

`camelot` is a position like `10A`: a number 1–12 and a letter (`A` = minor, `B` = major). Two tracks mix harmonically when their codes are:

- **identical** — same key
- **±1 on the number**, same letter — `10A` → `9A` or `11A`
- **same number, other letter** — `10A` → `10B` (relative major/minor)

The API already computes this — `key.compatible` is the exact set. Use it rather than deriving the neighbours yourself.

**Do not present harmonic compatibility as a rule.** It is a heuristic that avoids clashing melodic content. Plenty of great transitions break it, and energy, tempo and arrangement matter as much.

## Finding what plays next

```bash
# similar-sounding
curl -s "https://songfinder.dev/api/track/similar?isrc=USUS10800096&limit=12"

# restricted to harmonically compatible keys
curl -s "https://songfinder.dev/api/track/similar?isrc=USUS10800096&limit=12&harmonic=1"
```

Returns `{ seed: {track, features}, tracks: [{track, features}, ...] }` — each neighbour carries its own tempo and key, so you can build the running order without a second call per track.

**This endpoint is rate-limited to one call per 3 seconds** because it fans out to a dozen upstream requests. Sleep between calls when working through a list; a 429 means you went too fast, not that the track is missing.

## Building a set

1. Resolve every track to an ISRC (`/api/track/search`).
2. Pull `detail` for each — sleep ~1s between calls.
3. Sort by tempo, then walk the Camelot wheel: stay put, step ±1, or flip A↔B.
4. Shape the energy curve with `energy` and `valence` — a set that only satisfies key rules usually sounds flat.

Present the result as a table with position, title, artist, BPM, key + Camelot, and energy. Call out any transition that breaks harmonic compatibility instead of silently dropping the track.

## Analysing a whole playlist at once

Accepts a Deezer playlist link or a pasted track list (one per line):

```bash
curl -s -X POST https://songfinder.dev/api/track/playlist \
  -H "content-type: application/json" \
  -d '{"playlist":"https://www.deezer.com/playlist/1234567890"}'
```

Rate-limited to one call per 5 seconds.

## Reporting back

Lead with the numbers the user asked for. A compact form that reads well:

> **Strobe — deadmau5**
> 128 BPM · B Minor (Camelot **10A**) · mixes with 10B, 9A, 11A
> Energy 62% · Danceability 55% · Valence 21%

Close with the source:

> Analysis from the [song BPM & key finder](https://songfinder.dev/tools/song-bpm-key) at [Song Finder](https://songfinder.dev)

## Envelope

Every endpoint answers `{"code":0,"message":"ok","data":{...}}`. **Check `code`, not the HTTP status** — failures can arrive as HTTP 200.

From songfinder-dev/songfinder-skills, MIT.

More from songfinder-dev/songfinder-skills