xtc/docs/TRACK_INSERTS.md

# Track inserts

The sequencer's **Create** dropdown groups track creation, WAV import and
instrument loading. **View → Track inspector** opens the optional inspector;
it is hidden when the application starts to leave more room for editing.

Project format 17 stores up to eight effect slots per track, their order,
bypass, wet amount and chain output gain. Formats 1–16 read with empty chains.
Metadata load, clone and history never open executable plugin modules. Track
move, duplicate and removal retain the association with stable track IDs.
Nonempty bus chains are rejected. The model accepts mono effect specifications
for LADSPA, VST2, VST3, CLAP and internal effects; this alone does not establish
that a third-party binary is compatible with the host.

The chain API is declared in `xtc_plugin.h`. Setter errors preserve the old
chain; plugin identity and layout are checked when preparing playback.

Playback prepares an independent serial graph for each affected track. Audio
clips on the same track sum before its effects; instrument and scheduled MIDI
contributions also pass through their track graph. Effects run before track
and bus gain/pan, and meters observe their output. Wet/dry uses parallel gain
branches. Internal effect history resets at timeline discontinuities.

Each renderer owns its plans and preallocated raw buffers (up to 256 KiB per
affected track); processing uses blocks of at most 256 frames, with no host
allocation or I/O. Mono effect adapters require zero reported latency. External
plugin state on seeks follows the existing host contract. Bus inserts and
tracks containing both audio assets and MIDI reject preparation explicitly.
Live unassigned sine monitoring remains a separate master input.

Open **View → Track inserts** (or Ctrl+5 for the selected track) and choose a track. **Add effect** offers
internal Delay/Reverb and the plugin library. The left rack shows signal order;
the graph displays the actual generated graph compiled by playback. Wiring in
this view is read-only: edit the rack to preserve the serial chain. The global
Modular Graph remains independent. A failed plugin probe or playback preparation
preserves the current project; successful additions are undoable.

The library searches configured Preferences paths recursively (including VST3
bundle contents), with case-insensitive search and format filters. LADSPA and
VST2 both use `.so`, so those filters share candidates until inspection identifies
the ABI. Listing files executes no plugin code. Only inspect trusted binaries.

Select a slot in the rack, then use **Up**, **Down**, **Bypass** or **Remove**.
The selection follows reordered effects. Bypassed slots retain their settings
and appear marked in the rack; their nodes are omitted from the compiled graph.
Each successful operation creates one project undo step.

**Inspect / edit** verifies the selected plugin and opens its identity and generic
controls. Reset defaults clears parameter automation on Apply. Cancel leaves the
project unchanged. Internal effects and LADSPA expose controls; modern adapters
currently expose none and run default configurations. Native plugin editor
windows and opaque plugin-state chunks are not implemented.

**Preset → Save chain / Load chain** reuses the atomic versioned project file
container with one track. Order, bypass, wet amounts, output gain and exposed
controls/automation are retained. Loading metadata executes no plugin code;
applying it verifies all enabled plugins before replacing the current chain.
Preset files reference absolute installed binary paths, so another machine must
provide compatible binaries at those paths. No plugin binaries or opaque state
chunks are embedded.

**Insert wet** blends the selected effect with its input (0 dry, 1 fully wet).
**Chain gain** scales the complete chain before the track fader (0–4 linear).
Edits are prepared and undoable, with finite range validation. Internal sync
parameters follow project tempo. This is mono amplitude blending; stereo track
insert layouts, latency compensation and gapless live insert edits are future
work. Editing stops transport before preparing the replacement plan.

The CLI `xtc-check --inspect project.xtc` lists insert format, slot order,
bypass/wet settings and missing binary references without loading plugins.
VST3 processing supplies a fixed output-parameter sink (64 IDs, final point per
ID/block) for plugins that emit meter/parameter notifications; notifications are
not recorded or exposed as controls.

Host qualification on 2026-11-06 used the installed Linux x86_64 ZamEQ2,
ZamAutoSat and ZamDelay VST3 binaries under `/usr/lib/vst3`. All three were
prepared together, rendered with nonzero finite output and exported to WAV.
This verifies those default mono configurations, not arbitrary plugins or
physical hardware. The repository fixtures cover LADSPA, CLAP, VST2 and VST3
insert adoption and VST3 output notification bounds. Internal-plan allocation
failure and callback guards, sanitizers, GUI/JACK lifecycle and install checks
cover host ownership and cleanup.

Reproduce focused verification with:

```sh
make BUILD_DIR=build/audio-editor test-track-fx test-gui-track-fx
XTC_TEST_HOST_VST3=1 ./build/audio-editor/test_track_fx
```

The host opt-in requires the three named Zam bundles; the normal tests use
internal devices and controlled fixtures. The screenshot tool's
`XTC_CAPTURE_HOST_VST3=1` mode captures those real host plugins; see
[screenshots/README.md](../screenshots/README.md).