Samples & sample instruments
GameTank carts can play back imported PCM audio alongside (or instead of) synth voices. This tutorial imports a sample, wires it into a Sounds-tab instrument, and triggers it from Forth. Requires a GameTank cart (see The GameTank machine).
1. Import a sample
Open the Samples tab (it only appears on GameTank carts — M8 carts see a placeholder pointing back at the Cart tab's machine setting). Import decodes any audio file the browser can play, then runs it through a fixed pipeline:
- Decode — via the browser's
decodeAudioData. - Downmix to mono — stereo sources are collapsed to one channel.
- Resample — to whichever import rate you've selected (see the rate table below).
- Quantize to 8-bit PCM — the format native ROMs and the browser engine both play back.
There are 16 sample slots per cart. Deleting a slot shifts every later slot down by one — the editor warns you once, since any instrument referencing a shifted slot now points at the wrong sample.
2. Edit the waveform
The waveform editor renders the active sample as a canvas trace with two draggable markers — loop start and loop end. Numeric fields next to the canvas let you dial in exact sample-frame values; a loop toggle switches the sample between one-shot and looping playback. A Preview button plays the sample as authored, loop included.
Import rate (rate_code)
Every import is resampled to one of four fixed rates, picked in the Samples tab before you import:
rate_code | Rate |
|---|---|
| 0 | 22050 Hz (default, canonical) |
| 1 | 11025 Hz |
| 2 | 5513 Hz |
| 3 | 44100 Hz |
Lower rates cost proportionally fewer bytes per second of audio — trading fidelity for headroom against the 2,048-byte native budget. This table (and the full sample-instrument wiring below) is also covered from the Sounds tab's side in Sounds editor — Import rate.
3. Wire the sample into an instrument
Switch to the Sounds tab and open (or create) an instrument. GameTank instruments show a Kind toggle — Synth / Sample — that isn't present on M8. Switching to Sample replaces the ADSR sliders with three controls:
| Control | Effect |
|---|---|
| Smp | Picks which of the cart's up-to-16 sample slots this instrument plays, labeled by duration. |
| Pitch | Base pitch as a MIDI note number (0–127) with a live name readout (e.g. 69 · A4). Triggering the instrument at a different note repitches the sample relative to this base. |
| CH | The same channel-hint select synth instruments use. |
The ▶ test button and the transport bar's ▶ Play button both audition sample instruments in-studio, exactly as they'll sound on /play.
4. Trigger it from Forth
Sample instruments play back through the same audio words as synth instruments — nothing sample-specific about the call site. Reference the pattern that uses your sample instrument from play-sfx:
\ Trigger a sample-backed instrument via play-sfx on X-press.
: update
0 cls
6 btnp if 0 -1 play-sfx then ;
( pattern slot -- ) play-sfx fires pattern 0 (assumed to reference your sample instrument in at least one cell) on SFX slot -1 (auto-allocate the first idle slot). Full play-sfx/play-music/loop-sfx/stop-sfx coverage lives in Sounds editor — Music and SFX buses.