Cagire/docs/engine_samples.md

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.wav           → "kick"
├── snare.wav          → "snare"
└── hats/
    ├── closed.wav     → "hats" n 0
    ├── open.wav       → "hats" n 1
    └── pedal.wav      → "hats" n 2

Folders at the root of your directory are used as the name of a sample bank. Folders create sample banks where each file gets an index. Files are sorted alphabetically and assigned indices starting from 0.

Playing Samples

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
speed	any	Playback speed multiplier
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).

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.

Speed and Pitch

The speed parameter affects both tempo and pitch. A speed of 2 plays twice as fast and an octave higher.

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).

kick sound 440 freq .              ( play at A4 )
kick sound c4 .                    ( play at C4 )

Negative speed will reverse the sample and play it backwards.

crow sound -1 speed .              ( play backwards at nominal speed )
crow sound -4 speed .              ( play backwards, 4 times faster )

Fitting to Duration

The fit parameter stretches or compresses a sample to match a target duration in seconds. This adjusts speed automatically.

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.

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:

kick sound .                       ( plays kick.wav )
kick sound hard bank .             ( plays kick_hard.wav )
kick sound soft bank .             ( plays kick_soft.wav )