# 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) |
| `scanlfo` | Hz | LFO rate for scan modulation |
| `scandepth` | 0-1 | LFO modulation depth |
| `scanshape` | shape | LFO waveform |

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

## LFO Modulation

Automate the scan position with a built-in LFO:

```forth
pad 0 scan 2 scanlfo 0.3 scandepth .   ( 2 Hz modulation, 30% depth )
```

Available LFO shapes:

| Shape | Description |
|-------|-------------|
| `sine` | Smooth oscillation (default) |
| `tri` | Triangle wave |
| `saw` | Sawtooth, ramps up |
| `square` | Alternates between extremes |
| `sh` | Sample and hold, random 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.