96 lines
5.4 KiB
Markdown
96 lines
5.4 KiB
Markdown
# 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).
|