> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridshift.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Sample Library

> Index your sample folders, search by name or vibe, and swap samples on a track in real time — all from the keyboard.

The **Sample Library** keeps a central, searchable index of every audio file in the folders you've added. The index powers two workflows that share the same keyboard-first entry point:

* **Fast name search** through the Command Palette — find a sample and load it onto a track without leaving the keyboard.
* **Smart Search** (optional) — an on-device audio model sorts your library by how close each sample *sounds* to the one you're working with, so you can audition alternatives by vibe, not filename.

The payoff: while playback is running, you can step through samples with the arrow keys and hear each candidate in place on the current track, with zero drop-outs and no change to your clip layout.

## Indexed folders

Manage the library under `Gridshift → Settings → Samples`.

| Action          | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **Add Folder…** | Pick one or more folders. Subfolders are scanned recursively.    |
| **Rescan**      | Force a full rescan for a specific folder.                       |
| **−** (minus)   | Remove a folder from the library. Files on disk are not touched. |

Each row shows the folder's sample count and the time of the last scan.

### Supported formats

| Format   | Extensions      |
| -------- | --------------- |
| **WAV**  | `.wav`          |
| **AIFF** | `.aif`, `.aiff` |
| **MP3**  | `.mp3`          |
| **M4A**  | `.m4a`          |
| **CAF**  | `.caf`          |
| **FLAC** | `.flac`         |
| **OGG**  | `.ogg`          |

### Content-hash identification

Every file is identified by a **content hash**, not by its path. That means:

| Event                             | Result                                                                    |
| --------------------------------- | ------------------------------------------------------------------------- |
| File moved or renamed             | Automatically relinked on the next scan — project references keep working |
| File deleted                      | The library entry is marked stale; projects warn about missing media      |
| File contents changed             | Treated as a new sample                                                   |
| Duplicate file in a second folder | Recognized as the same sample (only one library entry)                    |

A file-system watcher keeps the index live. New files appear shortly after you drop them into an indexed folder, without a manual rescan.

<Info>
  Because identification is content-based, you can reorganize your sample folders freely. Projects that reference a moved sample pick it up automatically the next time Gridshift sees the file.
</Info>

### Cross-device sync

With iCloud enabled, the annotations you make on samples sync across your Macs:

* Ratings, colors, and tags
* Detected BPM and key
* Transient markers

Because samples are identified by content, these annotations follow the file rather than its location — rate a sample on one Mac and it's rated on every other Mac that has the same file indexed, even if you've organized your folders differently there.

The list of indexed folders is per-Mac, since file paths don't translate across machines. Add folders once on each Mac you use.

## Sample search via Command Palette

Open the picker with `⌥S` while a sample track is selected. Step through results with `↑` / `↓`, commit with `Return`, or cancel and revert with `Escape`.

The list re-ranks as you type. Ranking combines several signals:

| Signal                         | Effect                                                     |
| ------------------------------ | ---------------------------------------------------------- |
| **Exact / prefix / substring** | Direct filename matches rank highest                       |
| **Fuzzy subsequence**          | `khs` still finds `kick-hard-snap`                         |
| **Folder-name boost**          | Matches against ancestor folder names, decaying with depth |
| **Recency**                    | Samples you've used recently rank higher (7-day half-life) |
| **Favorites**                  | Starred samples appear in their own section at the top     |

Typing stays smooth even on libraries with tens of thousands of samples.

### Filter tokens

Combine a query with `:` tokens to narrow the list:

| Token                                                 | Filters to                      |
| ----------------------------------------------------- | ------------------------------- |
| `:short`                                              | Samples ≤ 2 seconds             |
| `:long`                                               | Samples ≥ 10 seconds            |
| `:mono`                                               | Single-channel files            |
| `:stereo`                                             | Two-channel files               |
| `:drums`, `:kick`, `:snare`, `:hat`, `:clap`, `:perc` | Auto-classified drum categories |
| `:vox`, `:vocal`                                      | Vocal categories                |
| `:bass`, `:synth`, `:pad`, `:fx`                      | Other tonal categories          |

Categories are inferred heuristically from filename and parent-folder tokens. A file under `.../Kicks/808/deep.wav` picks up `drums` and `kick` automatically.

<Tip>
  Tokens stack. `kick :short :mono` returns only short, mono kicks.
</Tip>

## Smart Search

Smart Search extends filename matching with **acoustic similarity**. Instead of relying on how files are named, Gridshift compares how they actually sound — using an on-device audio model.

### Enable Smart Search

Smart Search is opt-in. Toggle it under `Settings → Samples → Smart Search`:

<Steps>
  <Step title="Switch on Smart sample search" />

  <Step title="Gridshift downloads the model on first enable (around 170 MB)" />

  <Step title="A one-time indexing pass runs over your library in the background; Settings shows the progress" />
</Steps>

All processing runs on-device — no audio leaves your Mac.

### How you use it

Smart Search activates automatically once enabled. The sample picker picks the right mode based on what you do:

| Mode                  | Trigger                                                                   | Behavior                                                                                                      |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Similarity browse** | Open the picker with an empty query, on a track that already has a sample | The library is sorted by acoustic similarity to the current sample — the top entry is the closest sonic match |
| **Name search**       | Type letters                                                              | Falls back to classic filename scoring                                                                        |

<Tip>
  For drum replacement: open the picker on a snare track with nothing typed. Gridshift orders your library so the snares closest in character sit at the top — step through with `↑` / `↓` to audition alternatives quickly.
</Tip>

### Turn it off

Switching the toggle off returns the picker to pure name-based search. If you re-enable Smart Search later, it picks up where it left off without re-downloading the model or re-indexing your library.

## Swap samples during playback

The picker is designed for live, performative sample replacement. Clips keep their positions; only the underlying audio changes.

### Workflow

<Steps>
  <Step title="Select a sample track in the sidebar" />

  <Step title="Press ⌥S to open the picker" />

  <Step title="Step through results with ↑ / ↓">
    Each step:

    * Swaps the sample on the track **immediately and audibly** during playback.
    * Leaves clip offsets, lengths, and positions untouched.
    * Plays a full-length audition of the highlighted sample — except when playback is already running *and* the track has audio clips, where the clip-level preview is enough on its own.
  </Step>

  <Step title="Press Return to commit the current candidate" />

  <Step title="Press Escape to cancel and restore the original sample" />
</Steps>

Stepping through candidates is designed to feel instant — you can cycle dozens of samples per second without playback stuttering. Gridshift only creates a fresh waveform when you commit with `Return`; preview steps reuse the existing track in place.

### Edge cases

| Case                                                | Behavior                                                                                           |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| New sample is shorter than a clip's internal offset | The clip plays past the sample's end. Gridshift still allows the swap so you can judge the result. |
| No sample track selected                            | The picker shows an explanation ("Sample Track Required") instead of an empty list.                |
| Library is still empty                              | The picker shows "No Samples Indexed Yet" and points you at the Settings page to add a folder.     |

### Change a sample without preview

When you already know which file you want, two non-performative paths are also available:

| Method          | Description                                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| **Inspector**   | Click the sample name in the track inspector to open a Finder dialog.                                       |
| **Drag & Drop** | Drop an audio file from the [Browser](/features/inspector#browser) or Finder onto an existing sample track. |

Both create a fresh sound source immediately, with waveform and transients generated up front — no preview / commit loop.

## Shortcuts

The keys that drive the sample picker. The [Global Shortcuts](/shortcuts/global) reference has the complete grid of track and file operations.

| Action               | Shortcut  |
| -------------------- | --------- |
| Open sample picker   | `⌥S`      |
| Step through results | `↑` / `↓` |
| Commit selection     | `Return`  |
| Cancel and revert    | `Escape`  |
| Command Palette      | `⌘K`      |