Link the SDK

After building and installing, consume the install prefix from your application. Use package discovery rather than adding SDK source or build directories to your include path.

Discover and link the package

In the consumer’s CMakeLists.txt, request the exact SDK version and link the compatibility target:

cmake_minimum_required(VERSION 3.22)
project(treefall_consumer LANGUAGES CXX)

find_package(TreefallSDK 0.9.0 EXACT REQUIRED CONFIG)

add_executable(transport-consumer main.cpp)
target_compile_features(transport-consumer PRIVATE cxx_std_20)
target_link_libraries(transport-consumer PRIVATE Treefall::transport)

Configure and build against the isolated prefix:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH=/tmp/treefall-sdk-0.9.0-install \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build

Treefall::transport carries the transport controller and its public dependencies. Include installed public headers such as <treefall/transport_controller.h> and <treefall/version.h>. Existing applications may use the equivalent OrpheusSDK package, Orpheus::transport target, and <orpheus/...> headers; both package names resolve the same physical target graph.

Render a transport block

Create the controller with a TransportConfig, retain its fixed render contract, and provide exactly the configured number of writable planar buffers on every call. processAudio() is the sole audio consumer: call it from one non-reentrant audio thread with no more than maxBlockFrames frames. Do not put file opening, allocation, locks, logging, or host callbacks in that function.

The checked-in package smoke renders one silent 48 kHz, two-channel block with a 64-frame maximum and checks every sample:

example.transport-smoke · Product 0.9.0

Source revision: b8c8b87540fe585b5c7d5c8f25d193c1a1af93d5

// SPDX-License-Identifier: MIT
#include <treefall/transport_controller.h>
#include <treefall/version.h>

#include <array>
#include <cstddef>
#include <cstdint>
#include <iostream>
#include <memory>
#include <span>

int main() {
  try {
    constexpr std::uint32_t kSampleRate = 48000;
    constexpr std::uint32_t kChannels = 2;
    constexpr std::size_t kFrames = 64;

    const orpheus::TransportConfig config{
        .sampleRate = kSampleRate,
        .outputChannels = kChannels,
        .maxBlockFrames = static_cast<std::uint32_t>(kFrames),
        .maxActiveVoices = 1,
        .numGroups = 1,
        .maxSourceChannels = kChannels,
        .sourceChannelPolicy = orpheus::SourceChannelPolicy::Discrete,
    };
    auto transport = orpheus::createTransportController(nullptr, config);
    if (!transport || transport->getRenderConfig().maxBlockFrames != kFrames) {
      throw std::runtime_error("transport creation failed");
    }

    std::array<float, kFrames> left{};
    std::array<float, kFrames> right{};
    float* outputs[] = {left.data(), right.data()};
    transport->processAudio(outputs, kChannels, kFrames);
    for (const auto* channel : outputs) {
      for (const float sample : std::span<const float>(channel, kFrames)) {
        if (sample != 0.0f) throw std::runtime_error("non-silent output");
      }
    }

    std::cout << "Treefall SDK " << TREEFALL_SDK_VERSION << " transport smoke: 64 silent frames\n";
    return 0;
  } catch (const std::exception& error) {
    std::cerr << "transport smoke failed: " << error.what() << '\n';
    return 1;
  }
}

Treefall SDK 0.9.0 transport smoke: 64 silent frames

Source and producer-reported verification

Source-relative path

examples/transport-smoke.cpp

SHA-256

143beab36becdd09611b260f2e87d6a6ec354231173f2ad20dac625a2217ce07

Producer-reported verification

executed

Environment

os=darwin/arm64; cmake=cmake version 4.1.0; compiler=Apple clang version 21.0.0 (clang-2100.0.123.102)

Command

./examples-build/transport-smoke

Run the command shown with the rendered example to check the installed package. A null controller, changed render capacity, or nonzero sample exits before the success line.

If package discovery fails

• Version mismatch: remove the consumer build directory and set CMAKE_PREFIX_PATH to the intended install prefix only.
• Treefall::transport is missing: rebuild the SDK with ORPHEUS_ENABLE_REALTIME=ON, install into a new empty prefix, and configure again.
• Audio-file factories are null or NotReady: the SDK was installed without a usable file provider; follow the provider setup in Build and install.
• No device target on the current platform: use host-neutral rendering or Dummy. A successful package build does not make an unsupported hardware backend available.

For file-backed sources, complete the audio-file control-thread sequence before preparing transport input. For callback ownership and event draining, see realtime hosting.

The installed-target checks are exercised by the package smoke project, and the render contract is declared in the transport controller header.