Fetch

Fetch is a local, offline search and sorting tool for an existing sample library. Describe a sound in plain English, filter by instrument, genre, key, tempo or timbre, or ask for samples that sound like the one you have, and drag the results straight into your DAW.

It never modifies your sample files. All indexes, caches and settings live in your home directory.

Fetch targets Arch-based Linux with GNOME. It was developed on a Ryzen 7 8845HS (XDNA1 NPU) laptop with a library of tens of thousands of samples. The NPU part is optional.

Features

• Semantic search: CLAP audio–text embeddings, so dusty vinyl drum loop finds sounds even when their file names don't say so. File and folder names are also used in ranking.
• Similar sounds: find samples that match a given sample by timbre, key (Camelot neighbours) and/or BPM (±3 %, plus half/double time).
• Instruments, genres and types: Comprehensive instrument tree (Drums › Hats › Open, Bass › 808 …), style tags, per-pack genres, loop / one-shot detection. Read from names and folders first and estimated from the audio otherwise (estimated values are shown with ~).
• Key and tempo: read from file names (124bpm, _Gm, (125, C#min) …) or estimated from the audio.
• Sound features: brightness, bass, noisiness, attack and tail length, measured on the AMD XDNA NPU with IRON / mlir-aie (CPU fallback).
• GNOME integration:
  • Fetch window (GTK 4 / libadwaita) with instant playback, filters, collections and drag-and-drop to the DAW
  • Search from the Super key (fetch dark kick)
  • Files (Nautilus) extension: Similar sounds… menu, and Sound / Brightness / Tail / Folder columns
• Collections: Liked Samples lives in ~/Documents/Fetch Collections/ as hard links, so you can point your DAW's browser at it for quick access. Hard links take no extra space.

Search syntax

Works the same in the Fetch window, Super search and the command line.

Example	Meaning
warm rhodes chords	free text (English), ranked by sound and name
+dark +tight	sound-feature tags (see Sound-feature tags)
+loop, +oneshot, +other	sample type
bpm:120, bpm:118-126	tempo (±3 %, also half/double time)
key:Am, key:A, key:Am~	key; ~ adds compatible keys (Camelot neighbours)
inst:drums/perc, tag:female, genre:house	instrument, style tag, genre
snare loop -kick	-word excludes matches

Instrument, genre, type and pack words in free text also act as filters. Other words only affect ranking.

Requirements

• Arch-based Linux (pacman), GNOME with PipeWire
• uv, ffmpeg, Python 3.12 (venv) and the system Python with python-gobject, GTK 4, libadwaita, GStreamer and python-nautilus (the installers set these up)
• About 1 GB of disk space for the CLAP model (downloaded on first index)
• Optional: AMD Ryzen with an XDNA NPU (amdxdna driver, Linux ≥ 6.14) for the sound features

Installation

git clone https://github.com/kazio01/fetch.git
cd fetch

bash asenna.sh                  # Python env (.venv) + `samplehaku` command
samplehaku index ~/Samples      # build the CLAP index (slow for big libraries; re-runs only add changes)

bash asenna_npu.sh              # optional: XRT, permissions, IRON env, `samplehaku-piirteet`
samplehaku-piirteet             # sound features, key and tempo (NPU, or --backend cpu)

bash asenna_gnome.sh            # Fetch window + icon, Super search, Files extension
                                # then log out and back in
testit/aja.sh tests             # optional: check that everything works

Uninstall the GNOME parts with bash asenna_gnome.sh --uninstall. The index and your settings are kept.

The script names are Finnish (asenna = install, piirteet = features); everything they print is in English.

Usage

samplehaku-results                      # open Fetch (also in the app menu)
samplehaku                              # interactive terminal search (? = help)
samplehaku search "kick +dark" --key Am --bpm 124
samplehaku similar ~/Samples/kick_07.wav -t tight
samplehaku stats

Fetch window keys: ↑/↓ play, Space play/stop, ←/→ seek 10 %, L like, S similar, E edit tags, / or Ctrl+F search, Ctrl+A select all. Rows can be dragged into a DAW; the DAW receives the original file.

Super key: type fetch (or sample) followed by a search, e.g. fetch dark kick. A search containing a +tag or a filter works without the prefix. Clicking a result opens Fetch with the whole search and that sample selected.

Files: right-click an audio file › Similar sounds… to pick Timbre / Key / BPM. In list view, right-click the column header to add the Sound, Brightness, Tail and Folder columns; they work in any folder, including result folders.

Re-run samplehaku index … and samplehaku-piirteet after adding samples. Only new or changed files are processed.

Sound-feature tags

Tags are your own names for measured values, not trained models. Each tag picks the top or bottom share of your library for one feature, so +dark means the darkest third of your samples.

Tag	Feature
+dark / +bright	spectral centroid low / high
+bass	lots of energy below 150 Hz
+noisy / +tonal	noise-like / pitched
+punchy / +soft	fast / slow attack
+tight / +long	short / long tail (peak to −40 dB)

Edit ~/.config/samplehaku/tagit.json to rename, remove or add tags; changes apply immediately:

{"names": ["boomy", "warm"], "feature": "low", "direction": 1}

share sets how large a part of the library each tag covers (0.33 = a third).

How the NPU is used

On Hawk Point (XDNA1 / npu1) AMD's Ryzen AI software is not supported on Linux, so the NPU is programmed directly with the open IRON toolchain. The frequency transform (DFT) is written as a matrix multiplication: frames of 1024 samples × a 1024 × 1024 DFT matrix with the window function baked in, run as IRON's whole_array GEMM (bf16 in, f32 out) on all 16 AI Engine cores.

The NPU computes a 4096-frame spectrum in about 13 ms, compared with 24 ms on the CPU, and the results match the CPU within 0.23 %. On real files, decoding dominates, so the main benefit is a free CPU and lower power use. samplehaku-piirteet --selftest measures both on your machine.

samplehaku-piirteet --selftest       # NPU vs. CPU: accuracy and speed
samplehaku-piirteet --backend cpu    # without the NPU
samplehaku-piirteet --show kick.wav  # one file's values

Troubleshooting

• /dev/accel/accel0 is missing: check that the NPU (IPU) is enabled in the BIOS; sudo dmesg | grep -i amdxdna.
• XRT packages not found: they are in Arch's extra-testing repository; the installer can also build them from source.
• Permission denied / memlock: log out and back in (render group and memlock limit).
• NPU test fails: samplehaku-piirteet --backend cpu always works.

Customising

All settings are in ~/.config/samplehaku/:

File	Purpose
tagit.json	sound-feature tags (see above)
korjaukset.json	your own instrument/tag corrections (Edit tags… in the window)
genret.json	per-pack genres you have confirmed (Pack genres… in the window)
similar.json, ikkuna.json	remembered window and Similar settings

The search service runs in the background and stops after 10 idle minutes; change SAMPLEHAKU_IDLE_MIN (and the Super-search prefixes, SAMPLEHAKU_PREFIX) in ~/.config/systemd/user/samplehaku-haku.service. Log: journalctl --user -u samplehaku-haku -f.

Tests

testit/aja.sh                    # all tests + performance
testit/aja.sh tests              # tests only
testit/aja.sh performance        # performance only (compares with the previous run)

The tests run against your own indexed library and installation. Checks that need content your library doesn't have are skipped with a warning. Settings files are backed up and restored around the run.

See docs/DEVELOPMENT.md for the architecture.

License

Fetch is free software under the GNU General Public License v3.0.