match_sound
Read-onlyIdempotent
Rank your Ableton library by how closely each preset or rack sounds to a reference audio file, so you can find matching instruments or loops. Provide a stem, loop, or one-shot and get ranked candidates ready to load.
Instructions
Rank the library by how close each item sounds to a piece of audio you have.
Returns:
Dictionary with the descriptor taken from the file, the ranked candidates each
carrying its name, kind, category, library and score, and the call that loads
the one you pick.
Note:
A score orders this one answer, lower being closer: not a percentage or a distance,
and scores from two files do not compare. The order inside one answer is weaker than
it looks: ``elsewhere_in_the_file`` ranks a second stretch of the same recording to
show how weak; ``also_elsewhere`` says a candidate came back in both, the one
reading here that is evidence, not ordering. Measured 2026-09-19 over five separated
stems in 20 s windows, two windows of one stem shared about one name in ten and the
descriptor moved by three to six times the whole width of the top thirty. Ranked
over the whole library, the top candidate shared the probe's family 1 time in 7 at
20 s and 6 of 20 on 1.5 s slices: a bass stem answers with drum kits and a guitar
stem with pads; given ``instrument``, the same audio answers with basses and plucked
guitars. Name the family when you know it: this is a shortlist, not a ranking.
What is compared is Ableton's preview render of each item, so a busy-riff preview
describes itself differently from a held-chord one, and nothing here speaks for
playable range, velocity response or a single note's attack. The match is timbral
with level removed, so a quiet and a loud take of one sound match exactly; pitch is
not matched, so a bass line at 50 Hz and the same line at 100 Hz are near
neighbours. ``analysed`` says where the window landed, with peak and RMS; a silent
stretch answers ``nothing_to_match``, and without an index this answers
``no_index``. To load one, set ``track`` in its ``load_with`` block and call
``load_device``: the handle is a name, not a path, so the browser search can return
more than one item. Check before confirming.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the audio to match: a stem, a loop, a one shot. Any format the system decoder reads, which is WAVE, AIFF, MP3, Ogg, FLAC and ALAC. Not an Ableton factory sample: those are encrypted and nothing outside Live reads them. | |
| kinds | No | What to rank. 'loadable' is the default and means presets and racks, the things that go on a track. 'clips' ranks loops instead. | loadable |
| limit | No | How many candidates to return. | |
| window | No | Which part of the file to describe. 'loudest' is the default and finds the loudest stretch of 'seconds', which is what a stem needs: an instrument that plays a verse and rests through the chorus is silent for most of its own file. Loudest is not busiest: measured over five stems, the loudest window of a pad and of a keys part held no onsets at all. 'whole' averages everything, including the rests. 'at' takes 'seconds' from 'start_s'. | loudest |
| seconds | No | How long a stretch to describe, for 'loudest' and 'at'. Ignored by 'whole'. | |
| start_s | No | Where to start, for window='at' only. | |
| instrument | No | What kind of instrument this is, when you know. Set it whenever you do: a stem is usually named or obvious, and telling the tool is worth far more than any ranking. 'drum_kit' is a whole kit and 'drum_hit' is one cymbal or snare, which are never interchangeable. Empty ranks the whole library and is measurably the worse answer. | |
| category_contains | No | Narrow further inside the family by browser category text, case insensitive. Empty keeps the whole family. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||