Architecture diagrams

These diagrams summarize the pinned Treefall SDK architecture. They separate host policy and control-side preparation from the one non-reentrant audio consumer, and they show where bounded refusal or silence is intentional. The diagrams are explanatory views of the public contracts; they do not add an application scheduler, analyzer owner, or device backend.

Choose a diagramSDK layer topologyBounded control-to-audio flowPrepared-source streaming and underrun behavior

PreviousNext

Choose a diagram above, or use the left and right arrow keys when this gallery is focused.

SDK layer topology

Enlarge

Host applications and adapters consume the host-neutral SDK; platform providers sit below its stable contracts.

Rendering diagram…

View Mermaid source

flowchart LR
  app[Host application] --> adapter[Optional adapter]
  app --> sdk[Treefall SDK core]
  adapter --> sdk
  sdk --> files[Audio file provider]
  sdk --> dummy[Dummy driver]
  sdk --> coreaudio[CoreAudio on Apple]
  sdk --> wasapi[WASAPI source and fake-test path]
  classDef primary fill:#b8e986,stroke:#5c7f35,color:#101412
  classDef secondary fill:#20382a,stroke:#8ca995,color:#edf4ee
  classDef provider fill:#33453a,stroke:#b8e986,color:#edf4ee
  class app,adapter primary
  class sdk secondary
  class files,dummy,coreaudio,wasapi provider

Bounded control-to-audio flow

Enlarge

Concurrent control calls prepare state before bounded publication; one audio consumer processes commands and emits observations for the message thread.

Rendering diagram…

View Mermaid source

flowchart LR
  ui[UI and automation producers] --> prepare[Control-side preparation]
  midi[MIDI or OSC producers] --> prepare
  prepare --> ingress[255-node bounded MPSC ingress]
  ingress --> consume[Single audio consumer]
  consume --> render[processAudio: preallocated buffers]
  render --> events[Bounded SPSC event queue]
  events --> message[Message-thread callback drain]
  consume --> snapshot[Coherent telemetry snapshots]
  classDef primary fill:#b8e986,stroke:#5c7f35,color:#101412
  classDef secondary fill:#20382a,stroke:#8ca995,color:#edf4ee
  classDef warning fill:#5b4620,stroke:#d6a84d,color:#fff7df
  class ui,midi,prepare primary
  class ingress,consume,render secondary
  class events,message,snapshot warning

Prepared-source streaming and underrun behavior

Enlarge

Preparation and page filling stay off the callback; a cache miss is bounded silence plus telemetry rather than a blocking read.

Rendering diagram…

View Mermaid source

flowchart LR
  path[Media path] --> prep[Control-thread preparation]
  prep --> source[Immutable prepared source]
  source --> worker[Worker-fed page ring]
  worker --> pages[Ready PCM pages]
  pages --> callback[Audio callback]
  callback --> output[Rendered output]
  worker -. cache miss .-> callback
  callback --> silence[Silence plus BufferUnderrun]
  classDef primary fill:#b8e986,stroke:#5c7f35,color:#101412
  classDef secondary fill:#20382a,stroke:#8ca995,color:#edf4ee
  classDef warning fill:#5b4620,stroke:#d6a84d,color:#fff7df
  class path,prep primary
  class source,worker,pages,callback,output secondary
  class silence warning

Enlarged diagram

Close

Scroll or pan within the diagram when its layout is wider than the view.

Reading the views

• Layer topology keeps host applications and optional adapters above the host-neutral SDK and platform providers below it.
• Bounded command flow shows control producers publishing into the fixed ingress pool while the audio thread consumes without allocation, locks, or I/O. Message-thread code drains callback events.
• Prepared-source streaming shows control-side preparation and worker-fed pages. A cache miss renders silence and reports BufferUnderrun; the callback never waits for file I/O.

Source authority

• ARCHITECTURE.md
• docs/REALTIME_AUDIT.md
• include/orpheus/transport_controller.h