# Wavetables

Any sample can be played as a wavetable. When you use the `scan` parameter, the sample automatically becomes a pitched oscillator that can morph between cycles.

## What is a Wavetable?

A wavetable is a series of single-cycle waveforms stored end-to-end in an audio file. Each cycle is a complete waveform that starts and ends at zero crossing, allowing it to loop seamlessly at any pitch.

```
Sample: [cycle 0][cycle 1][cycle 2][cycle 3]
         ↑                           ↑
      scan 0                      scan 1
```

The oscillator reads through one cycle at audio rate (determining pitch), while `scan` selects which cycle to play. Values between cycles crossfade smoothly, creating timbral morphing.

## Basic Usage

Just add `scan` to any sample and it becomes a wavetable:

```forth
pad 0 scan .                 ( play pad as wavetable, first cycle )
pad 0.5 scan .               ( blend to middle cycles )
pad 440 freq 0 scan .        ( play at A4 )
```

Without `scan`, the sample plays normally. With `scan`, it becomes a looping wavetable oscillator.

## Parameters

| Parameter | Range | Description |
|-----------|-------|-------------|
| `scan` | 0-1 | Position in wavetable (0 = first cycle, 1 = last) |
| `wtlen` | samples | Cycle length in samples (0 = entire sample) |

## Cycle Length

The `wtlen` parameter tells the engine how many samples make up one cycle. This must match how the wavetable was created, otherwise you'll hear the wrong pitch or glitchy artifacts.

```forth
pad 0 scan 2048 wtlen .      ( Serum-style 2048-sample cycles )
pad 0 scan 1024 wtlen .      ( 1024-sample cycles )
```

Common cycle lengths are powers of two: 256, 512, 1024, 2048. Serum uses 2048 samples per cycle. The number of cycles in a wavetable is the total sample length divided by `wtlen`. If `wtlen` is 0 (default), the entire sample is treated as one cycle. The sample still loops as a pitched oscillator, but `scan` has no morphing effect since there's only one cycle.

## Scanning

The `scan` parameter selects which cycle to play:

```forth
pad 0 scan .                 ( first cycle only )
pad 0.5 scan .               ( blend between middle cycles )
pad 1 scan .                 ( last cycle only )
```

## Scan Modulation

Use audio-rate modulation words to automate the scan position:

```forth
pad 0 1 2 lfo scan .                ( sine LFO, full range, 2 Hz )
pad 0 0.5 1 tlfo scan .             ( triangle LFO, half range, 1 Hz )
pad 0 1 0.5 jit scan .              ( random scan every 0.5 steps )
```

## Creating Wavetables

A proper wavetable file:

- Contains multiple single-cycle waveforms of identical length
- Each cycle starts and ends at zero crossing for seamless looping
- Uses power-of-two cycle lengths (256, 512, 1024, 2048)
- Has cycles that morph smoothly from one to the next

You can find wavetable packs online or create your own in tools like Serum, WaveEdit, or Audacity (using zero-crossing snap). Single-cycle waveforms also work. With `wtlen` set to 0, a single-cycle sample becomes a basic pitched oscillator.
