> ## 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

> Keeps your samples and MIDI patterns in one managed library you can browse, hear and place. Press ⌥S to swap a track's sample while the song plays, or ⌘Y for the library window.

## Swap samples during playback

<video src="/videos/sample-library-swap.mp4" poster="/videos/sample-library-swap.jpg" aria-label="While the song plays, Option S on the Snare track opens the sample picker; the down arrow swaps in other snares and Return keeps one" title="While the song plays, Option S on the Snare track opens the sample picker; the down arrow swaps in other snares and Return keeps one" muted loop playsInline preload="none" />

Select a sample track and press `⌥S` (**Load Sound…**). Each `↑` / `↓` swaps the sample on the track at once, in place. `Return` keeps it, `Escape` puts the original back.

## Fill the library

Open `Gridshift → Settings → Library` and run **Import Samples and MIDI Files…**, or click **+** in the library window's toolbar, and pick a folder. Or drop files onto the library window, or onto a collection in its sidebar.

## Place a sample from the library window

Press `⌘Y` to open the library window. Select a row and press `Space` to hear it, then drag it onto the arrangement, or right-click and choose **Insert on New Track** to place it at the play cursor.

## Insert files from disk

Drop audio, MIDI or ReCycle files from the Finder onto the arrangement, or onto an existing sample track to change its sample. Or run Command Palette → **Insert Files from Disk** and pick files: each lands on a new track at the cursor.

## Which page do you need

* [Find Samples](/library/find-samples.md): search, chips, Find Similar and duplicates.
* [Organize Samples](/library/organize-samples.md): collections, tags, favorites, names and the Trash.
* [Tempo, Key and Type](/library/tempo-key-and-type.md): hear rows in your project's tempo and key, loops versus one-shots, the library tempo.
* [Smart Search](/library/smart-search.md): find samples by how they sound.
* Patterns (`.mid` files) have their own picker: [Patterns](/sounds/patterns.md). Presets live in the library too: [Instrument Presets](/sounds/instrument-presets.md) and [Effect Presets](/sounds/effect-presets.md).

## Good to know

* **Importing copies the files into a folder Gridshift owns**, `~/Music/Gridshift/Samples`. The library is one thing you can back up, sync and offload. The folders you imported from are sources, not homes.
* **Folder names below the one you picked become tags.** Import `Splice` and a file at `Splice/Drums/Kicks/Distorted` keeps **Drums**, **Kicks** and **Distorted**. The picked folder is left out, because it would land on every sample alike.
* **Putting a sample on a track does not import it.** A project carries its own reference to the file, so the library stays the list you chose to keep. ReCycle loops are the exception.
* **A swap leaves clip offsets, lengths and positions untouched.** Only the audio changes. On an instrument track `⌥S` adds Instruments and Presets tabs, and a sample picked there loads the built-in [Sampler](/samples/sampler.md) in place of the instrument: [Load Instruments and Effects](/sounds/load-instruments-and-effects.md).
* **The audio itself does not sync until you say so.** Favorites, tags and collections follow the file to your other Macs; the audio has its own switches: [iCloud](/sync/icloud.md).

> **Details**
>
> * **A sample is identified by its content hash, not its path.** The same audio imported twice, from two folders or two Macs, is one sample with one set of tags. Moving or deleting the source folder changes nothing. The index is at `~/Library/Application Support/Gridshift/library.db`.
> * **MIDI files import alongside audio.** `.mid` and `.midi` files become patterns for the `⌥P` picker.
> * **`.dat` files with WAV or AIFF audio import as ordinary samples**, such as the samples of a Loopcloud Play kit. Other `.dat` files are skipped.
> * **A ReCycle loop becomes a WAV on import.** Its slices become transient markers, like markers placed by hand, and its tempo becomes the sample's BPM. Gridshift's own analysis leaves both alone, and both sync to your other devices and the [iPhone](/sync/iphone-library.md).
> * **Dropping a ReCycle loop on the timeline imports it first**, also when inserted from the file browser, and places the WAV. Importing it again changes nothing, and markers or a tempo you edited stay.
> * **A REX file wins over its WAV twin.** When an import has both with the same name, Gridshift imports the REX file, which has the slices, and skips the WAV. The import dialog says how many WAVs it skipped.
> * **An unreadable loop is named with the reason**, for example a file with every slice muted. The rest of the import carries on.
> * **Dropping a single instrument note on empty timeline makes an instrument track** with the sampler and an empty four-bar MIDI clip. Hold `⌥` while dropping for an audio track.
> * **Changing a sample without preview builds it up front.** Click the sample name in the track [Inspector](/get-started/the-window.md) to pick a file in a Finder dialog, or drop a file on the track. A fresh sound source is made at once, with waveform and transients. Drops come from the library window or the Finder.
> * **On a sample track with no sample, click the empty Sample slot in the Inspector** to open the same picker as `⌥S`. Dropping an audio file on the slot loads that file.
> * **The library window also opens** from `File → Sample Library…` or Command Palette → **Open Sample Library**.
> * **The sidebar has four sections.** **Samples** and **Patterns** each list **All**, **Unsorted** and their collections. **Instrument Presets** and **Effect Presets** list your [instrument presets](/sounds/instrument-presets.md) and [effect presets](/sounds/effect-presets.md). The **Trash** at the bottom holds what you deleted from all four. The `+` beside a section heading makes a collection of that kind.
> * **Right-click the table header to choose columns.** Name, Waveform, Status, a favorite star, Tags, BPM, Type, Key, Length and Added. **Type** is off until you turn it on. Every column sorts except the waveform. **Added** is the date the sample came into the library; its first click puts the newest imports on top.
> * **Status says where the bytes are.** On this Mac only, on this Mac and in iCloud, in iCloud with only the small copy here, or missing because the file is no longer where the library left it. Sorting on it gathers the missing ones into one block.
> * **A missing sample keeps its row, favorite and tags.** Only playing it and revealing it in Finder are refused.
> * **A small-copy sample comes back in full** once the selection rests on it for a moment, so the editor opens without a wait. To fetch several ahead of time, select them, right-click and choose **Download from iCloud**; it appears only when some of the selection is not on this Mac.
> * **A multi-row selection drags as one drop.** **Insert on New Track** makes one track per selected item.
> * **Letter keys play the selected sample's slices or notes** in the library window, and `⌥X` opens the [Sample Editor](/samples/sample-editor.md) for it.
> * **`⌘K` in the library window lists that window's commands**: file into a collection, set tags, set the play mode, open the editor. Each takes a shortcut of your own: [Command Palette](/work-fast/command-palette.md).
> * **The picker is one list**, with no separate Recent or Favorites block. It re-ranks as you type and shows every match, loading more as you scroll. Searching it: [Find Samples](/library/find-samples.md).
> * **Each picker step plays a full-length audition** of the highlighted sample, except while playback runs and the track has audio clips, where the clip-level preview is enough. Preview steps reuse the existing track in place; a fresh waveform is made only on `Return`.
> * **A shorter sample still swaps.** If it is shorter than a clip's internal offset, the clip plays past its end so you can judge the result.

> **Supported formats**
>
> | Format | Extensions |
> | - | - |
> | **WAV** | `.wav` |
> | **AIFF** | `.aif`, `.aiff` |
> | **MP3** | `.mp3` |
> | **M4A** | `.m4a` |
> | **CAF** | `.caf` |
> | **FLAC** | `.flac` |
> | **OGG** | `.ogg` |
> | **ReCycle** | `.rx2`, `.rex`, `.rcy` |
> | **MIDI** | `.mid`, `.midi` |

> **Picker messages**
>
> | Case | Behavior |
> | - | - |
> | No track selected | The picker shows "No Track Selected" |
> | A track that is neither sample nor instrument | The picker shows "Sample or Instrument Track Required" |
> | First import still running | The picker shows "Indexing Your Sample Library…" until it finishes |
> | Library is still empty | The picker shows "No Samples Indexed Yet". Import a folder under `Settings → Library` |

> **Keys**
>
> | Action | Shortcut |
> | - | - |
> | Load Sound… (the picker) | `⌥S` |
> | Step through results / commit / cancel and revert | `↑` `↓` / `Return` / `Escape` |
> | Open the Sample Library window | `⌘Y` |
> | Walk the list, also while the search field has focus | `↑` / `↓` |
> | Play or stop the selected sample | `Space` |
> | Play the selected sample's slices or notes | Letter keys |
> | Edit the selected sample | `⌥X` |
> | Command Palette with this window's commands | `⌘K` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.