xtc/docs/BUILTIN_DEVICES.md

# Internal instruments and effects

No plugin downloads, search paths or external libraries are needed. The original
built-in sine remains available for existing projects.

Choose **Internal: Soft Keys** or **Internal: Sub Bass** in a MIDI track's
instrument dropdown. Soft Keys blends a sine with a third harmonic; Sub Bass
uses a pure sine. Both have 32 voices, velocity sensitivity,
short attack/release envelopes, sustain pedal, note-off and panic handling.
High harmonics are omitted near Nyquist. The default sounds remain compatible with fixed presets from v13. See the
Phase 41 controls below. A sample library is not provided by these oscillators.

In **Modular Graph**, select a wire and choose **Edit → Insert internal delay on
wire** or **Insert internal reverb on wire**. This preserves the route and inserts
the effect into the signal path. **File → Add internal delay/reverb** creates an
unconnected device for manual wiring. Select its node and use **Edit → Selected
plugin control** to edit it, or **Selected plugin automation** to automate it.
Changes use the existing stopped-engine preparation and undo workflow.

- **Delay:** time (1–2000 ms), feedback (0–0.95), dry/wet mix (0–1).
- **Reverb:** four parallel damped feedback combs, with decay (0–0.95), damping
  (0–0.95) and dry/wet mix (0–1). Decay is a feedback coefficient, not seconds.

These are basic mono processors; stereo plans use independent instances. Reverb
is deliberately simple and has no room model or stereo diffusion. Delay time
changes can click; there is no crossfade or tempo sync. Transport seeks retain
existing effect history, like LADSPA. Effect tails require continued rendering;
playback/export does not automatically extend the song for tails.

Project format 13 stores internal devices as format 4 with reserved module path
`/xtc/internal`, stable numeric identity and index (0 keys, 1 bass, 2 delay,
3 reverb). This is a virtual identifier, never an external binary. Effect controls
and automation are saved using the existing plugin records; instruments are fixed
presets. Readers still accept formats 1–12. Older xtc builds reject format 13.
All buffers are allocated during preparation; processing performs no allocation,
file access, library loading, locking or GUI calls.

Validation: `make BUILD_DIR=build/phase38 all gui test test-gui-instruments
 test-gui-modern-plugins test-gui-plugins analyze` (join onto one line).
`test-builtins` checks impulse tails, dry mix, feedback bounds, block partition
consistency, note release/panic and instrument/effect project round trips.

## Phase 40 acceptance checks

`make BUILD_DIR=build/phase40 all gui test test-reliability test-gui builtin-preview`
checks all four device identities and GUI paths without external plugin binaries.
The reliability runner fails each internal preparation allocation in turn and
forbids allocation/free, direct file I/O and blocking locks during processing.
Core tests compare persisted rendering for both instruments and both automated
effects, corrupt an internal module identity transactionally, and cover voice
exhaustion, sustain, repeated notes, partitioning and transport reset/seek/panic.
The existing portability suite verifies older project migrations.

For repeatable manual listening, run `make builtin-preview` and audition
`build/builtin-{0,1,2,3}.wav` at a conservative level: 0 is Soft Keys, 1 Sub Bass,
2 Delay and 3 Reverb. Each six-second file includes held tones or two impulses
followed by silence for tails. Check onset/release, unwanted discontinuities,
finite decay and the documented mono character. Generation is verified;
human listening and physical-device qualification remain pending.

## Phase 41 instrument controls and presets

**Edit → Selected instrument controls** edits an assigned internal instrument.
The five ports are harmonic amount (0..1), attack (0.1..2000 ms), release
(1..5000 ms), low-pass cutoff (20..24000 Hz; 24000 bypasses the filter) and
pitch-bend range (0..24 semitones, default 2). The harmonic is a third harmonic;
it is suppressed before crossing Nyquist. Attack/release are exponential time
constants, not times to absolute silence. Defaults preserve the original sounds.

**Selected instrument automation** accepts `port tick mode value`, with absolute
project ticks, linear mode 0, hold mode 1, or -1 to remove a point. Automation
uses absolute sample positions, including seeks and 256-frame instrument chunks.
Static edits stop/reprepare playback and are undoable. Existing v13 assignments
with no parameters upgrade to defaults when opened in the editor.

**File → Save/Load instrument preset** uses an explicit absolute path. Presets
are versioned single-instrument `.xtc` containers with no clips. Public C APIs
`xtc_plugin_preset_save/load` provide atomic saving and transactional metadata
loading; they never execute plugin code. Loading into a track is an undoable,
prepared edit. Parameter automation is included. Preset paths are ordinary files;
saving uses the existing project replacement semantics.

Live MIDI pitch bend uses standard 14-bit messages (8192 center) and is applied
at the event's sample offset per channel. Panic clears the affected channel's
bend and sustain. The original unassigned sine ignores bend; CLAP MIDI/VST2
receive raw bend, while native-note CLAP/VST3 do not yet map it to expressions.
No external-plugin parameter support is implied.

Format 14 adds instrument controls and automation. Readers still accept v1–v13;
old fixed internal assignments use their original defaults. Older builds reject
v14. Tests cover legacy-default sound equality, v13 migration, parameter/preset
round trips, pitch-bend offsets, automated block partitions, undo and GUI edits.