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.

Phase 28 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.

Phase 31 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.

## Phase 32 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.