xtc/docs/KNOWN_LIMITATIONS.md

# Known Limitations and Qualification Boundaries

- Development version 0.1.0, Linux C99/C++17/FLTK, optional JACK.
  Physical-device playback/capture, human transition listening, independent user
  acceptance and long-duration device qualification are pending.
- Fixed 4/4 and constant tempo snapshots; no tempo map, loop transport, plugin
  latency compensation, limiter, background streaming or multichannel mixer
  buses.
- Mono capture/import downmix; stereo track output. Graph ports are mono with
  independent paired processing. Maximum 64 project graph nodes (256
  standalone), 64 tracks, 1024 clips/automation points, 4096 scheduled notes,
  256 live MIDI events/block, 32 voices, 65536 frames/block. See API headers for
  exact bounds.
- WAV samples preload with the memory/format limits in AUDIO_FILES.md. Callback
  overflow reports/silences; there is no CPU preemption or expensive-plugin
  rescue.
- Live MIDI configurable per-channel volume/pan/sustain CC mapping; no
  controller learn, capture, SMF import, pitch bend, custom-instrument chooser
  or instrument timbre controls.
- Native ABI 1 graph nodes are session-only. ABI 2 state is parameter-only.
  LADSPA supports the documented mono amp/inverter/sine set; no opaque state,
  native editor, MIDI, true multichannel layout, latency compensation or crash
  isolation. Automated LADSPA controls use run(1) and can be expensive.
- GUI loading/compilation is synchronous on the control thread. Timeline grid/
  zoom/selection and graph positions are session UI state. Undo retains 32 edits
  plus baseline and at most one reserved metadata snapshot; GUI edits reserve
  history before mutation/publication. Media is never removed by undo/delete.
  Broad screen-reader/accessibility testing is pending.
- Format v12 reads v1–v11 and uses relative local media references. External
  absolute media/module paths need manual repair after relocation. Saving does
  not bundle media; missing media stays referenced, missing plugins reject GUI
  installation. Unknown data is rejected rather than stripped. Post-rename
  directory-sync errors can report failure even though the complete new document
  was published.
- No autosave/session crash restoration, RF64, system service, automatic
  dependency installation or public signed release. Source/binary archives are
  local artifacts; binary packages require compatible system libraries. No
  third-party plugin or dependency binary is bundled. Power-cut durability
  depends on the filesystem.

See ROADMAP.md, AUDIO_QUALITY.md, CONTROL.md, WORKFLOW.md, PROJECT_FORMAT.md,
PERFORMANCE.md, PLUGIN_HOSTING.md and RECOVERY.md for tested contracts/evidence.

- Waveform previews load synchronously on the control thread and cache at most
  64 paths/1024 bins each. Reopen after external media replacement. Audio cuts
  use tick resolution; GUI safety fades can create a short dip at split edges.
  Time stretching, independent pitch shifting and crossfades are deferred.

- Graph folders, per-track graph routing and track templates remain deferred:
  timeline and MIDI sources expose shared mixes. Layout is session-only; no
  feedback cycles, plugin isolation or latency compensation are supplied.

- Stereo one-level mix buses share the 64-track limit. Nested buses, independent
  bus plugin inserts, per-track aux sends and sidechains remain deferred. Track
  meters are pre-bus; bus meters are pre-graph; master is post-graph. Sample
  peaks and sticky clipping do not provide loudness, true-peak analysis or
  limiting.

- Plugin discovery is an explicit-file descriptor browser, not a directory scan.
  Generic parameter dialogs own copied metadata; no native plugin editors or
  custom MIDI instrument chooser. LADSPA units are unspecified. Replacement
  requires the same mono audio layout and resets controls/automation. Missing
  modules reject Open while retaining the current project; GUI module relink for
  unopened documents is deferred. In-process plugin crashes/hangs are
  uncontained.

- Common parameter targets cover track/bus gain/pan, LADSPA controls and
  metadata for live sine volume/pan/sustain. Live mappings do not drive arranged
  lanes, faders or plugins. No automation capture, touch/latch/write modes or
  loop transport. Backward jumps are deterministic for lanes, not opaque plugin
  tails.

- Editing feedback remains synchronous; busy cursors are not background loading
  or cancellable progress. Surviving selections are retained across undo but
  historical selection/layout is not stored. Native context-menu/focus manual
  qualification and broad accessibility testing remain pending. See EDITING.md.

Project diagnostics use syntax-line locations; semantic cross-reference failures
identify the MODEL stage without a source line. `xtc-check --inspect` checks
dependency file availability only, without loading code or WAV contents. The
project format is Linux/POSIX oriented; absolute plugin paths, architecture, ABI
and JACK/device configuration must be supplied on another system. Unknown fields
are rejected, not preserved. See PROJECT_FORMAT.md for versions 1–10 and
RECOVERY.md for save failures after rename.

CLAP/VST2/VST3 loading supports Linux binary modules, one-input mono float32
zero-latency effects at default configuration. No modern parameter edit,
automation, programs, opaque state, MIDI/instruments, transport, custom editor,
workers, sidechains or true stereo/multichannel buses are implemented. Plugin
bundles must be opened at their actual Linux shared-library binary. Only
original ABI fixtures are qualified; arbitrary third-party modern plugins remain
untested. See PLUGIN_HOSTING.md and decision 0010 for lifecycle and licensing
boundaries.

---

## Instrument Support

MIDI tracks can bind CLAP, VST2 and VST3 instruments. In the Track menu, select
**Load instrument plugin** for the selected sequencer track; **Use built-in
instrument** removes the binding. Assignment also selects the track for live
MIDI. **Live MIDI to selected instrument** changes that target; **Live MIDI to
built-in sine** restores the legacy live source. MIDI clip notes always go to
their own track's instrument. Independent instances feed track gain/pan,
mute/solo, bus routing and automation. Bindings/live target save in v12.

Supply the actual trusted Linux binary (including the inner .so of a VST3
bundle). Supported instruments have zero audio inputs, one mono output, float32
processing, zero latency and one note/event input. Default configuration only:
no custom editor, opaque state/preset restoration, modern parameter
editing/automation, stereo/multichannel instruments or MIDI output. No arbitrary
third-party instrument is qualified by the original ABI fixture tests.

CLAP accepts MIDI or native notes; VST2 uses MIDI events; VST3 uses IEventList
note events. Live CC reaches CLAP MIDI/VST2; native CLAP/VST3 have no controller
mapping (including sustain). Live MIDI goes to exactly one selected target.
Seeks/loops retrigger notes crossing the destination with fresh envelopes;
plugin oscillator/opaque DSP state cannot be reconstructed. Panic delivers
all-off (VST3 held-key note-offs); plugin release tails may remain. Processing
uses preallocated 256-frame chunks and 256 incoming events per instance/chunk;
overflow or processing failure silences the block and schedules reset events.
The existing 32 simultaneous scheduled-note and 4096 stored-note bounds remain.
Do not unload/replace modules during playback; candidate plans are prepared off
the callback and old instances are reclaimed on the control thread. Missing
references remain inspectable without loading; failed GUI preparation retains
the current project. Save a backup for applications limited to v11 or earlier.

### Track insert chains

Track chains contain at most eight mono effects. Modern adapters require zero
reported latency, use default configuration and do not provide native plugin
windows, parameter editing or opaque state persistence. A bounded VST3 output
parameter sink retains the final notification per parameter per block (64
parameters); these notifications are not recorded or exposed as controls. Track
edits stop transport before candidate preparation. Bus inserts and tracks with
both audio assets and MIDI reject preparation. Unassigned live sine monitoring
stays on the master input. Stereo insert layouts, latency compensation,
sandboxed scanning and gapless live insert edits remain future work. Internal
history resets on discontinuities; third-party history follows the existing host
contract. Presets retain absolute plugin references, so compatible binaries must
be installed at the same paths on another machine. The smaller optional
inspector's visibility is session-local.