xtc/docs/STEINBERG.md

# Steinberg SDK integration (Phase 106)

The VST3 host uses Steinberg's pinned generated C ABI in the C99 core. Optional
SDK examples now also build against the full, separately supplied official C++
SDK and run Steinberg's validator. This adds an independent interoperability
check without adding a C++ runtime or network dependency to libxtc.

## Working integration

- Linux `.vst3` bundles resolve to
  `Contents/<architecture>-linux/<bundle-stem>.so`. Direct `.so` paths still
  work. The original chosen path remains the saved identity reference. This
  supports conventional bundles, not arbitrary renamed modules or Windows DLLs.
- VST3 processing receives sample rate, absolute sample position, tempo and
  musical position (`samples / rate * BPM / 60`). Position follows the existing
  effect/instrument `_at` APIs, including seek. Tempo is the prepared plugin
  spec's milli-BPM value; reprepare when it changes. Processing is marked playing
  because this API represents active rendering, including offline rendering.
  Loop, recording, wall-clock, time signature and continuous-time flags are not
  asserted: the current plugin API does not carry that information. Positions
  above `INT64_MAX` reject before processing, matching VST3's signed sample clock.
- Original SDK-built examples expose a mono half-gain effect and a mono,
  16-channel sine instrument. The instrument handles note-on/off at their exact
  block offsets; the host translates all-notes-off to held-note releases.
- The C render example demonstrates the actual xtc plugin facade and WAV writer,
  including no-clobber output, without requiring JACK or a GUI.

Enable the root CMake integration with `-DXTC_BUILD_STEINBERG=ON` and
`-DXTC_VST3_SDK_ROOT=/path/to/vst3sdk`, build, then run
`ctest --test-dir build --output-on-failure -R steinberg`. Normal builds leave
the SDK option off. The example subdirectory also remains a standalone CMake
entry point for native SDK/ASIO diagnostics.

See [the example instructions](../examples/steinberg/README.md) for SDK versions,
build commands, validation and ASIO diagnostics.

## Screenshots

![SDK Half Gain loaded in xtc's insert graph](../screenshots/steinberg-sdk-track-insert.png)

The actual SDK-built effect in xtc's host. See its
[identity dialog](../screenshots/steinberg-sdk-identity.png), the
[SDK Sine instrument chooser](../screenshots/steinberg-sdk-instrument.png) and
[capture commands](../screenshots/README.md#steinberg-and-juce-sdk-integration-phases-106107).
These examples have no custom editor; the screenshots show xtc's host interface
with playback stopped. They do not demonstrate ASIO hardware operation.

## ASIO and VST2 scope

ASIO is native driver I/O, separate from VST plugin hosting. The optional Windows
diagnostic enumerates drivers and inspects an explicitly selected driver's
channels, sample types, current sample rate, buffer bounds and reported latency.
It does not create/start audio buffers and is **not an xtc ASIO backend**.
The current xtc engine/backend still targets Linux/POSIX and JACK/PipeWire.
Windows portability, a C API platform bridge and native-driver qualification
are remaining Phase 106 work, not simulated by Linux tests.

VST2 support retains the existing original minimal ABI declarations. VST3's SDK
does not include the discontinued VST2 SDK. No VST2 SDK or user plugin is copied,
fetched or licensed by these build targets.

## Remaining work

The application VST3 adapter still accepts one mono input (or no audio input for
instruments), one mono output, float32 and zero reported latency. Its two mono
instances are not a native stereo plugin instance. It uses plugin defaults;
controller parameters, opaque-state persistence and custom editor windows remain
unimplemented in xtc. The SDK examples include an edit-controller class for
standard SDK-host compatibility; xtc does not instantiate it yet. The examples
have no editable parameters or opaque state, so they do not prove those paths.
No VST extension support or general third-party compatibility is inferred from
the validator passing these examples.

The complete acceptance checklist is in [Phase 106](ROADMAP.md#phase-106--steinberg-vst-sdk-and-asio-integration).