Treefall SDK

Professional audio SDK for broadcast, live performance, and DAW applications

Treefall SDK is the current name of this host-neutral C++20 audio SDK; it was formerly the Orpheus SDK. The GitHub repository was renamed to match and the earlier chrislyons/orpheus-sdk slug still resolves. Native library, executable, and package names and the canonical orpheus C++ namespace remain technical compatibility identities, so the rename requires no consumer source, build, or binary change. Treefall provides deterministic session/transport control, sample-accurate clip playback, and real-time audio infrastructure.

Current version: 0.9.1 (pre-1.0 SDK; stable C ABI 1.0). The authoritative value is project(orpheus VERSION ...) in CMakeLists.txt; tools/version_contract.py synchronizes public claims and CI rejects drift.

⚡ Quick Start

New to Treefall SDK? Get up and running in under 5 minutes:

# Clone repository
git clone https://github.com/boot-industries/treefall-sdk.git
cd treefall-sdk

# Build SDK (Debug with AddressSanitizer)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j8

# Run the configured SDK contracts
ctest --test-dir build --output-on-failure

Prerequisites:

• CMake 3.22+
• C++20 compiler: VS 2022 MSVC, Apple Clang with libc++, or GCC 11+
• libsndfile (audio file I/O): Homebrew, apt, or vcpkg package

Next Steps:

• Review current contracts: SUPPORT_MATRIX.md and REALTIME_AUDIT.md define the active platform, capability, and realtime posture.
• Historical qualification records: ORP qualification and handoff records remain local provenance only and are intentionally not part of the public checkout.
• View Changelog: See CHANGELOG.md

Compatibility names

The installed package is available as both TreefallSDK and OrpheusSDK, and both discovery paths expose the same underlying libraries. New integrations may use Treefall:: targets, include/treefall/... forwarding headers, and treefall as the C++ namespace alias. Existing Orpheus:: targets, include/orpheus/... headers, and the orpheus namespace remain supported.

The C ABI remains version 1.0. Treefall C typedefs, TREEFALL_* macros, and treefall_* ABI/error/logger/telemetry wrappers are additive entry points over the existing tables and state; old orpheus_* names and layouts remain available. An appended C++ virtual extension preserves source compatibility for recompiled implementations, but every C++ consumer and subclass must be rebuilt against the matching headers. No legacy surface has a removal date; removal requires a separately approved major migration.

The checkout directory is local and need not match the product name: existing worktrees may still be named orpheus-sdk, while the clone command above creates treefall-sdk. The root CMake project remains project(orpheus VERSION ...) for compatibility.

Lightweight Integration Targets

For downstream integrations that only need diagnostics or audio utilities, link the thin targets instead of the full session/transport stack:

find_package(TreefallSDK CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Treefall::diagnostics Treefall::audio_utils)

The legacy spelling remains equivalent:

find_package(OrpheusSDK CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Orpheus::diagnostics Orpheus::audio_utils)

• Treefall::diagnostics (also Orpheus::diagnostics) exposes performance_monitor.h and loudness_meter.h. Use createStandalonePerformanceMonitor() when no SessionGraph is involved.
• Treefall::audio_utils (also Orpheus::audio_utils) exposes file I/O and format-conversion helpers plus trigger_voice.h, the allocation-free one-shot voice utility used by host-owned sequencers and generated tracks.

CoreAudio Route Reliability

CoreAudio I/O selection is direction-specific. Input and output identifiers are persistent HAL DeviceUID values; an empty identifier selects only that direction's current system default.

orpheus::AudioDriverConfig audio;
audio.input_device_id = selectedInputUID;
audio.output_device_id = selectedOutputUID;
audio.num_inputs = 2;
audio.num_outputs = 2;

auto driver = orpheus::createCoreAudioDriver();
if (driver->initialize(audio) == orpheus::SessionGraphError::OK) {
  const auto io = driver->getTelemetry();
  // io.input_render_failures distinguishes capture failure from real silence.

  const auto start_error = driver->start(callback);
  if (start_error != orpheus::SessionGraphError::OK) {
    const auto failed_io = driver->getTelemetry();
    if (failed_io.route_outcome == orpheus::AudioRouteRuntimeOutcome::BackendFailure &&
        failed_io.route_backend_error != 0) {
      // failed_io.route_backend_error is the platform-native start status.
    }
    // Reinitialize explicitly after handling a terminal route outcome.
  }
}

Distinct CoreAudio endpoints use a driver-owned private aggregate. Unknown or
direction-incompatible UIDs fail with `InvalidParameter`; they never fall back
to another endpoint. During an active route, listeners close the render gate
and a control worker verifies the physical devices and format. A refused rate
restore, endpoint loss, or format change stops rendering; the driver never
silently changes an endpoint or rate.
See the tracked `ARCHITECTURE.md`, [`SUPPORT_MATRIX.md`](docs/SUPPORT_MATRIX.md),
and [`REALTIME_AUDIT.md`](docs/REALTIME_AUDIT.md) for active contracts and support
posture. The referenced route-compatibility handoff is a local ORP engineering
record, intentionally not linked from the public README.

Windows/WASAPI is not yet a release-supported backend. The implementation is
present, but hosted Windows package/ABI proof and a real-device acceptance
artifact remain required; see the [support posture in `AGENTS.md`](AGENTS.md#sources-of-truth).

---

## Table of Contents

- [Feature Highlights](#feature-highlights)
- [Core Capabilities](#core-capabilities)
- [Repository Layout](#repository-layout)
- [CoreAudio Route Reliability](#coreaudio-route-reliability)
- [Supported Platforms](#supported-platforms)
- [Getting Started](#getting-started)
  - [C++ Toolchain](#c-toolchain)
  - [Optional Targets](#optional-targets)
  - [Running Tests](#running-tests)
- [Demo Workflows](#demo-workflows)
  - [Standalone Demo Host](#standalone-demo-host)
  - [Render a Click Track](#render-a-click-track)
- [Applications Built on Treefall SDK](#applications-built-on-treefall-sdk)
- [Tooling & Quality](#tooling--quality)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

## Feature Highlights

The SDK provides comprehensive clip playback control, metadata persistence, and professional workflow features:

### 🎚️ Gain Control API

```cpp
// Per-clip gain adjustment (-96 to +12 dB)
transport->updateClipGain(handle, -6.0f);  // Half amplitude

🔁 Loop Mode API

// Seamless clip looping (no fade-out at boundary)
transport->setClipLoopMode(handle, true);

💾 Persistent Metadata

// Batch update all clip settings (survives stop/start cycles)
ClipMetadata metadata;
metadata.trimInSamples = 1000;
metadata.gainDb = -6.0f;
metadata.loopEnabled = true;
transport->updateClipMetadata(handle, metadata);

⚡ Seamless Restart & Seek

// Gap-free restart from IN point (sample-accurate)
transport->restartClip(handle);

// Sample-accurate seek for waveform scrubbing
transport->seekClip(handle, position);

🎛️ ORP109 Professional Features

Added 2025-11-11: Seven major features for professional workflows:

// 1. Routing Matrix - Professional N×M audio routing
auto routing = createClipRoutingMatrix(sessionGraph, 48000);
routing->assignClipToGroup(clipHandle, 0);
routing->setGroupGain(0, -3.0f);

// 2. Audio Device Selection - Runtime device management
auto driverManager = createAudioDriverManager();
auto devices = driverManager->enumerateDevices();
driverManager->setActiveDevice(deviceId, 48000, 512);

// 3. Performance Monitoring - Real-time CPU/latency diagnostics
auto perfMonitor = createPerformanceMonitor(sessionGraph);
auto metrics = perfMonitor->getMetrics();

// 4. Waveform Pre-Processing - Fast UI rendering
auto reader = createAudioFileReaderExtended();
auto waveform = reader->getWaveformData(0, duration, 800, 0);

// 5. Scene/Preset System - Snapshot management
auto sceneManager = createSceneManager(sessionGraph);
std::string sceneId = sceneManager->captureScene("Act 1");

// 6. Cue Points/Markers - In-clip navigation
transport->addCuePoint(handle, 120000, "Verse 1", 0xFF0000FF);
transport->seekToCuePoint(handle, 0);

// 7. Multi-Channel Routing - 8-32 channel interfaces
routing->setClipOutputBus(clipHandle, 2);  // Route to channels 5-6

Features: 7 new APIs, 23 new data structures, 165+ new tests Documentation: Active guidance is maintained in the public headers, ARCHITECTURE.md, SUPPORT_MATRIX.md, and REALTIME_AUDIT.md; local ORP records remain explicitly non-public provenance.

---

See: CHANGELOG.md for full release notes Current contracts: See the public headers, SUPPORT_MATRIX.md, and REALTIME_AUDIT.md; release notes remain in CHANGELOG.md.

Directional endpoint discovery and playback routing

IAudioDriverManager::enumerateEndpointCapabilities() returns persistent backend device IDs, independent input/output channel descriptors, current format facts, and the directional system-default flags. Use those IDs for route selection; display names are not stable identifiers.

auto manager = createAudioDriverManager();
for (const auto& endpoint : manager->enumerateEndpointCapabilities()) {
  if (endpoint.supports_output && endpoint.is_default_output) {
    auto driver = createCoreAudioDriver();
    AudioOutputRouteRequest route{
        .output_device_id = endpoint.device_id,
        .output_channel_map = {0, 1},
        .requested_sample_rate = 48000,
        .requested_buffer_size = 512,
    };
    if (driver->initializeAudioOutput(route) == SessionGraphError::OK) {
      // Start the playback-only driver with the application callback.
    }
  }
}

An empty AudioOutputRouteRequest::output_device_id follows the current default output. A non-empty ID is strict: unsupported, unavailable, or directionally incompatible IDs fail initialization rather than falling back. getAudioIoRouteState() exposes the selected IDs, active physical route, channel maps, actual format, latency terms, and a detail string. Poll it on a control thread after an I/O failure; InputUnavailable and OutputUnavailable identify a distinct failed duplex endpoint.

setEndpointChangeCallback() is notification-only. On CoreAudio it runs on an internal control worker, never the realtime audio callback or the CoreAudio property-listener thread. The callback may replace or unregister itself, or destroy the manager. It must arrange application-thread re-enumeration and must not perform realtime work.

---

Overview

The Treefall SDK provides deterministic session/transport control for professional audio applications. Built for broadcast and live performance with 24/7 reliability.

Key Design Principles:

1. Host-neutral Core – C++20 library works across DAWs, plugins, and standalone apps
2. Real-time Safe – Zero allocations on audio thread, lock-free command processing
3. Sample-accurate – ±0 sample tolerance for transport operations
4. Deterministic – Same input → same output, always (bit-identical)

Core Capabilities

Transport & Playback

• Multi-clip transport – Simultaneous clip playback (tested with 16 clips)
• Gain control – Per-clip gain adjustment (-96 to +12 dB)
• Loop mode – Seamless clip looping with boundary enforcement
• Trim points – Sample-accurate IN/OUT boundaries
• Fade curves – Linear, EqualPower, Exponential
• Restart/Seek – Gap-free position control (±0 samples)
• Cue points – In-clip markers with seek-to-cue (ORP109)

Audio I/O

• Audio file reader – WAV/AIFF/FLAC via libsndfile. The ORPHEUS_SNDFILE_PROVIDER=Auto|SndFile|PkgConfig|None CMake choice resolves one imported provider target; None builds dependency-free stubs and raw producer paths never enter installed exports.
• Platform drivers – CoreAudio (supported), Dummy (supported); WASAPI and Linux device backends are not yet release-supported
• Offline render-to-disk – Call public transport processAudio synchronously, then interleave/write after each call returns. The installed offline recipe uses no device, sleeps, or callback-time file I/O.
• Codec preflight – Query SDK format policy and exact writer tuples before allocating media objects; separately probe actual file headers on a background thread.
• Dummy driver – Timed device-loop simulation for testing, not the offline seam.
• Device selection – Direction-specific stable input/output IDs; persistent CoreAudio DeviceUIDs and owned duplex aggregates (ORP155)
• Capture and rate diagnostics – Factory-visible saturating input-render failure telemetry plus runtime nominal-rate recovery/reinitialization outcomes (ORP155, ORP128)

Routing & Mixing

• Routing matrix – Professional N×M routing with aggregate and logical lane metering, and bounded schema-3 telemetry (ORP109, ORP257)
• Multi-channel – Support for 2-32 channel configurations (ORP109)
• Clip Groups – 4 Clip Groups → Master (simplified API for OCC)

Performance & Diagnostics

• Performance monitoring – Real-time CPU/latency/underrun tracking (ORP109)
• Routing-level metering – Sample/RMS/SDK true-peak lanes plus the retained legacy routing LUFS proxy; standalone K-weighted loudness analysis is a separate control/offline facility (ORP257)
• Callback timing histogram – Opt-in jitter profiling; disabled by default (ORPHEUS_ENABLE_AUDIO_CALLBACK_TIMING=OFF) and active only with an attached performance monitor
• Bounded realtime telemetry – Decimated transport/routing/diagnostic snapshots for message-thread consumers

Workflow Management

• Scene/Preset system – Lightweight snapshot management (ORP109)
• Session JSON – Human-readable format with metadata persistence
• Metadata persistence – Clip settings survive stop/start cycles
• Stable session transactions – Stable-ID edits, rollback, revisioned change sets, and pointer-free snapshots
• Media integrity and recovery – Versioned SHA-256 fingerprints, explicit resolution states, atomic save, and schema migration

Developer Tools

• Session graphs – Tempo maps, clip grids, metadata storage
• ABI negotiation – Deterministic host/plugin compatibility
• Click-track rendering – Via minhost CLI adapter
• Comprehensive tests – 270+ unit tests (165+ ORP109), AddressSanitizer clean

Repository Layout

├── adapters/           # Host integrations (minhost CLI, REAPER extension)
├── apps/               # In-tree apps (wave-finder smoke shell, juce-demo-host)
├── cmake/              # CMake helper modules and compiler policies
├── docs/               # Architecture, roadmaps, API reference, ORP documents
├── include/            # Public C++ headers (install these with your app)
├── packages/           # Shared C++/JUCE app packages (occ-app-platform, shmui-juce)
├── src/                # Core library implementation (C++20)
│   ├── core/           # Transport, routing, audio I/O, session
│   └── platform/       # Platform-specific drivers (CoreAudio, WASAPI, ASIO)
├── tests/              # GoogleTest unit tests (270+ tests, sanitizer-clean)
└── CHANGELOG.md        # Release notes and version history

Package status (one authoritative sentence each):

• packages/occ-app-platform — active C++ application-platform helpers (session recovery, preferences, health telemetry) consumed by the external Clip Composer repo through its SDK submodule.
• packages/shmui-juce — active JUCE UI component library (waveform, meters, transport widgets) consumed by downstream JUCE apps; not part of the core SDK libraries.
• The former TypeScript packages (@orpheus/engine-*, @orpheus/client, @orpheus/shmui) are archived as part of the C++ SDK focus; they are not part of this repository.

Supported Platforms

The host-neutral core, Dummy driver, installed package, and conformance fixtures are required on macOS, Windows, and Linux. Device backend support is narrower: CoreAudio is supported on macOS; WASAPI is not yet a supported release backend; and ALSA, JACK, and PipeWire are not implemented. For exact compiler, architecture, backend, and unavailable-capability status, see the support posture in AGENTS.md. Planned backends are not shipped capabilities.

Getting Started

C++ Toolchain

1. Install the prerequisites:

   • CMake 3.22+
   • A C++20-capable compiler (MSVC 2019+, Clang 13+, or GCC 11+)
   • Ninja or Make (optional, for faster incremental builds)

2. Configure, build, and test the core library:

   cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
   cmake --build build
   ctest --test-dir build --output-on-failure

   These commands produce the orpheus_core static library, build the orpheus_minhost adapter, and run the GoogleTest suite by default.

Optional Targets

Additional components are disabled unless explicitly requested during configuration:

• Real-time audio infrastructure (M2 modules, enabled by default):

  # Required for the public transport-to-disk offline recipe as well as playback
  cmake -S . -B build -DORPHEUS_ENABLE_REALTIME=ON

  Includes:

  • orpheus_transport – Lock-free transport controller for clip playback
  • orpheus_audio_utils – Audio analysis and file I/O (file I/O requires libsndfile)
  • orpheus_audio_io – Host-neutral audio I/O and Dummy driver

  Install libsndfile: brew install libsndfile (macOS) or vcpkg install libsndfile (Windows)

• JUCE demo application – build an interactive host for session inspection:

  cmake -S . -B build -DORPHEUS_ENABLE_APP_JUCE_HOST=ON
  cmake --build build --target orpheus_demo_host_app

• Host integrations – toggle adapters with the documented CMake cache entries in the top-level CMakeLists.txt.

Running Tests

Run all tests with detailed output:

# All tests (270+ tests, core unit suite ~2 seconds)
ctest --test-dir build --output-on-failure

# Specific test suite
./build/tests/transport/clip_gain_test        # Gain control tests
./build/tests/transport/clip_loop_test        # Loop mode tests
./build/tests/transport/clip_metadata_test    # Metadata persistence tests

# 16-clip stress test (60 seconds runtime)
./build/tests/transport/multi_clip_stress_test

Test Coverage:

• Gain control: 11/11 tests passing
• Loop mode: 11/11 tests passing
• Metadata persistence: 10/10 tests passing
• Integration: 16-clip stress test (60s, no memory leaks)

Development Workflow

Multi-Instance Development

This repository supports running multiple Claude Code instances simultaneously for focused development:

SDK Instance (Core Library Development)

Working Directory: ~/dev/orpheus-sdk (repository root)

Focus: C++ core library, cross-platform packages, SDK-level infrastructure

Start Instance:

cd ~/dev/orpheus-sdk
claude-code

Use For:

• Core library changes (src/, include/)
• Transport, routing, session management
• SDK-level tests and benchmarks
• Cross-platform compatibility
• Documentation in tracked public guidance (ARCHITECTURE.md, docs/); local ORP records are not required.

Clip Composer Instance (Application Development)

Clip Composer is an external downstream repository — chrislyons/clip-composer (local checkout: ~/dev/clip-composer). It consumes this SDK as a git submodule at third_party/orpheus-sdk. The former in-tree apps/clip-composer/ subdirectory was archived on 2026-07-09; the archival record is local provenance only.

Use the Clip Composer repo for:

• Application-specific features, UI components, and workflows
• OCC documentation (docs/occ/ in that repo)
• App builds and CI (both live there, not here)

Use this SDK repo for: the transport, routing, audio_io, and ABI work Clip Composer depends on — then bump the submodule pin in the app repo.

When to Use Which Repo

Task	Repo	Reason
Fix transport controller bug	SDK	Core library modification
Add new clip button feature	Clip Composer	Application UI change
Update audio driver	SDK	Platform infrastructure
Implement session dialog	Clip Composer	Application-specific UI
Add routing matrix test	SDK	Core library testing
Fix waveform display	Clip Composer	Application UI component

See also: AGENTS.md Multi-Instance Usage section for complete documentation

Demo Workflows

Standalone Demo Host

OrpheusDemoHost dynamically loads the Orpheus ABI shared libraries at runtime and mirrors the demo workflow:

1. File → Open Session… – load a session JSON file.
2. Session → Trigger ClipGrid Scene – negotiate the clip grid.
3. Session → Render WAV Stems… – write rendered stems to disk.

The executable (OrpheusDemoHost plus the platform extension) is emitted inside your build directory.

Render a Click Track

Use the minhost CLI to generate a two-bar click track with an overridden tempo:

./build/orpheus_minhost \
  --session tools/fixtures/solo_click.json \
  --render click.wav \
  --bars 2 \
  --bpm 100

Omit --render to run a transport simulation and print the proposed render graph instead of writing audio.

Tooling & Quality

• Sanitizers – AddressSanitizer and UBSan are enabled automatically for Debug builds on non-MSVC toolchains.
• Formatting & linting – GitHub Actions runs clang-format against the C++ sources. A project-wide .clang-tidy configuration is available for local static analysis, but it is not currently a required CI gate.
• Continuous Integration – GitHub Actions builds and tests the C++ targets on Linux, macOS, and Windows, verifies sanitizer builds, and checks for accidentally committed binary artifacts.

To experiment with clang-tidy locally, configure a build with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON and invoke clang-tidy -p build (or the LLVM run-clang-tidy.py helper) on the files you want to inspect.

Applications Built on Treefall SDK

The Treefall SDK provides the foundation for a family of professional audio applications:

Orpheus Clip Composer (OCC) — external repo

Professional soundboard for broadcast, theater, and live performance

• Repo: chrislyons/clip-composer — a standalone downstream repository that consumes this SDK as a git submodule (third_party/orpheus-sdk). Extracted from this repo's former apps/clip-composer/ subdirectory on 2026-07-09 (archival record retained as local provenance).
• Features: Clip triggering (384 buttons, 960-slot capacity), waveform editing, multi-channel routing, operator modes, cue-bus audition
• Market: Broadcast playout, theater sound design, live performance
• Documentation: docs/occ/ in the Clip Composer repo (not here)

SDK Requirements: Real-time transport, audio drivers (CoreAudio/ASIO/WASAPI), routing matrix, performance monitor

Orpheus FourTrack — external repo

Portastudio-style multitrack recorder for macOS/iOS

• Repo: chrislyons/fourtrack (local: ~/dev/fourtrack) — consumes this SDK as a git submodule; exercises the SDK's host-neutral routing matrix, readers, CoreAudio directional input capture, capture telemetry, and allocation-free trigger voice.

Orpheus Wave Finder (in-tree)

App-platform smoke-test shell (apps/wave-finder/)

• Status: In-tree development shell exercising packages/occ-app-platform. Note: this is NOT the real FreqFinder analyzer, which lives in its own external repo (~/dev/freqfinder).

Orpheus FX Engine

LLM-powered effects processing and creative workflows

• Status: Planned — not yet started
• Features: DSP integration, real-time parameter automation, LLM hooks

---

Documentation

PREFIX Registry

ORP Docs (SDK): PREFIX: ORP Next Doc: ORP138 Local ORP records: The SDK maintains ignored engineering records for historical planning and handoff provenance. They are not public documentation links and are not required to build or consume the SDK. Historical ORP files use the workspace PREFIX convention but remain ignored local records rather than shipped documentation.

OCC Docs (Clip Composer): live in the external Clip Composer repo (chrislyons/clip-composer, docs/occ/) — not in this repository.

Documentation follows workspace pattern docs/<prefix>/<PREFIX><NUM>.(md|mdx) — see the workspace AGENTS.md for full conventions.

Reference Documentation

• CMakeLists.txt – adapter and optional-target build flags.
• ROADMAP.md – planned milestones and long-term initiatives.
• ARCHITECTURE.md – design considerations for the modular core.
• Clip Composer repo – Orpheus Clip Composer application + OCC documentation (external)
• AGENTS.md – coding assistant and repository workflow guidelines

Contributing

Issues and pull requests are welcome. Please discuss substantial changes in an issue before opening a PR so design goals remain aligned. Follow the existing code style (.clang-format, .clang-tidy) and ensure ctest passes locally before submitting.

License

This project is released under the MIT License.