Raphaël Forment
8e43e1bb3c
All checks were successful
Deploy Website / deploy (push) Has been skipped
165 lines
5.3 KiB
Markdown
165 lines
5.3 KiB
Markdown
# Samples
|
|
|
|
The `sample` source plays audio files from disk with pitch tracking.
|
|
|
|
## Loading Samples
|
|
|
|
There are two ways to load samples:
|
|
|
|
* **From the app:** Navigate to the Engine view and find the Samples section. Press `A` to open a file browser, then select a folder containing your samples. Press `D` to remove the last added path.
|
|
|
|
* **From the command line:** Use the `-s` flag when launching Cagire:
|
|
|
|
```
|
|
cagire -s ~/samples -s ~/more-samples
|
|
```
|
|
|
|
The engine scans these directories and builds a registry of available samples. Samples load in the background without blocking audio. Supported file formats are `.wav`, `.mp3`, `.ogg`, `.flac` and `.aiff`.
|
|
|
|
## Folder Organization
|
|
|
|
```
|
|
samples/
|
|
├── kick/ → "kick"
|
|
│ └── kick.wav
|
|
├── snare/ → "snare"
|
|
│ └── snare.wav
|
|
└── hats/
|
|
├── closed.wav → "hats" n 0
|
|
├── open.wav → "hats" n 1
|
|
└── pedal.wav → "hats" n 2
|
|
```
|
|
|
|
Folders at the root of your sample directory become sample banks named after the folder. Each file within a folder gets an index. Files are sorted alphabetically and assigned indices starting from `0`.
|
|
|
|
## Playing Samples
|
|
|
|
```forth
|
|
kick sound . ( play kick sample )
|
|
hats sound 2 n . ( play third hat sample )
|
|
snare sound 0.5 speed . ( play snare at half speed )
|
|
```
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Range | Description |
|
|
|-----------|-------|-------------|
|
|
| `n` | 0+ | Sample index within a folder (wraps around) |
|
|
| `begin` | 0-1 | Playback start position |
|
|
| `end` | 0-1 | Playback end position |
|
|
| `slice` | 1+ | Divide sample into N equal slices |
|
|
| `pick` | 0+ | Select which slice to play (0-indexed, wraps) |
|
|
| `speed` | any | Playback speed multiplier |
|
|
| `stretch` | 0+ | Time-stretch factor (pitch-independent) |
|
|
| `freq` | Hz | Base frequency for pitch tracking |
|
|
| `fit` | seconds | Stretch/compress sample to fit duration |
|
|
| `cut` | 0+ | Choke group |
|
|
|
|
## Slicing with Begin/End
|
|
|
|
The `begin` and `end` parameters define what portion of the sample plays. Values are normalized from 0 (start) to 1 (end).
|
|
|
|
```forth
|
|
kick sound 0.25 begin 0.75 end . ( play middle half )
|
|
kick sound 0.5 begin . ( play second half )
|
|
kick sound 0.5 end . ( play first half )
|
|
```
|
|
|
|
If begin is greater than end, they swap automatically.
|
|
|
|
## Slice and Pick
|
|
|
|
For evenly-spaced slicing, `slice` divides the sample into N equal parts and `pick` selects which one (0-indexed, wraps around).
|
|
|
|
```forth
|
|
break sound 8 slice 3 pick . ( play the 4th eighth of the sample )
|
|
break sound 16 slice step pick . ( scan through 16 slices by step )
|
|
```
|
|
|
|
Combine with `fit` to time-stretch each slice to a target duration. `fit` accounts for the sliced range automatically.
|
|
|
|
```forth
|
|
break sound 4 slice 2 pick 1 loop . ( quarter of the sample, fitted to 1 beat )
|
|
```
|
|
|
|
## Speed and Pitch
|
|
|
|
The `speed` parameter affects both tempo and pitch. A speed of 2 plays twice as fast and an octave higher.
|
|
|
|
```forth
|
|
snare sound 2 speed . ( double speed, octave up )
|
|
snare sound 0.5 speed . ( half speed, octave down )
|
|
snare sound -1 speed . ( play in reverse )
|
|
```
|
|
|
|
For pitched playback, use `freq` or note names. The sample's base frequency defaults to middle C (261.626 Hz).
|
|
|
|
```forth
|
|
kick sound 440 freq . ( play at A4 )
|
|
kick sound c4 . ( play at C4 )
|
|
```
|
|
|
|
Negative speed will reverse the sample and play it backwards.
|
|
|
|
```forth
|
|
crow sound -1 speed . ( play backwards at nominal speed )
|
|
crow sound -4 speed . ( play backwards, 4 times faster )
|
|
```
|
|
|
|
## Time Stretching
|
|
|
|
The `stretch` parameter changes sample duration without affecting pitch, using a phase vocoder algorithm. This contrasts with `speed`, which changes both tempo and pitch together.
|
|
|
|
```forth
|
|
kick sound 2 stretch . ( twice as long, same pitch )
|
|
kick sound 0.5 stretch . ( half as long, same pitch )
|
|
kick sound 0 stretch . ( freeze — holds at current position )
|
|
```
|
|
|
|
Combine with `slice` and `pick` for pitch-locked breakbeat manipulation:
|
|
|
|
```forth
|
|
break sound 8 slice step pick 2 stretch . ( sliced break, stretched x2, original pitch )
|
|
```
|
|
|
|
Reverse playback is not available with `stretch` — use `speed` for that.
|
|
|
|
## Fitting to Duration
|
|
|
|
The `fit` parameter stretches or compresses a sample to match a target duration in seconds. This adjusts speed automatically.
|
|
|
|
```forth
|
|
kick sound 0.25 fit . ( fit kick into quarter second )
|
|
snare sound beat fit . ( fit snare to one beat )
|
|
```
|
|
|
|
## Choke Groups
|
|
|
|
The `cut` parameter assigns a sample to a choke group. When a new sample with the same cut value plays, it kills any currently playing samples in that group.
|
|
|
|
```forth
|
|
hihat_closed sound 1 cut . ( choke group 1 )
|
|
hihat_open sound 1 cut . ( kills closed hat, starts open )
|
|
```
|
|
|
|
This is essential for realistic hi-hat behavior where open and closed hats shouldn't overlap.
|
|
|
|
## Bank Variations
|
|
|
|
Add `_suffix` to sample names to create variations that share the same base name.
|
|
|
|
```
|
|
samples/
|
|
├── kick.wav
|
|
├── kick_hard.wav
|
|
├── kick_soft.wav
|
|
```
|
|
|
|
Select variations with the `bank` parameter:
|
|
|
|
```forth
|
|
kick sound . ( plays kick.wav )
|
|
kick sound hard bank . ( plays kick_hard.wav )
|
|
kick sound soft bank . ( plays kick_soft.wav )
|
|
```
|