Status: milestone 1 (functional audio vertical slice). Decisions marked ADR have their own record in docs/adr/.
┌──────────────────────────────────────────────────────────────────────────┐
│ UI (Rust, Slint + custom wgpu surfaces) crates/dstudio-app │
│ • declarative shell, panels, controls (Slint) │
│ • GPU timeline / waveforms / meters (wgpu) → ADR 0001 │
│ • holds NO authoritative state; renders from Document + engine readouts │
└───────────────▲───────────────────────────────┬──────────────────────────┘
│ revision-change notifications │ Command (validated)
┌───────────────┴───────────────────────────────▼──────────────────────────┐
│ Application core (Rust) crates/dstudio-core │
│ • model: Project / Track / Clip / Asset / Transport (musical time) │
│ • command: serialisable, validated, invertible edit commands │
│ • history: Document = project + undo/redo + coalescing + revisions │
│ • persist: versioned JSON project dir, external media references │
│ • snapshot: musical → sample-frame conversion, immutable session desc │
│ • (next) keymap with context predicates, AI tool schema, plugin catalog │
└───────────────┬──────────────────────────────────────────────────────────┘
│ SessionSnapshot → C ABI (engine/include/dstudio_engine.h)
┌───────────────▼──────────────────────────────────────────────────────────┐
│ Audio engine (C++23) engine/ (static library) │
│ • non-RT side: asset decode + resample, graph build, retire queue │
│ • RT side: audio callback → render graph, transport, meters, stats │
│ • platform devices: Core Audio │ WASAPI (ASIO: future) │ PipeWire │
│ • plugin hosting: VST3 / CLAP (all OSes), AU (macOS), OOP scanner │
└──────────────────────────────────────────────────────────────────────────┘
Optional services (AI, cloud catalog) sit beside the core and talk to it only through Commands.
| Thread | Owns | May not |
|---|---|---|
| UI / main | Document, UI state, event loop |
block on audio, touch engine memory |
| Workers | file decode (se_asset_load_file), peak computation, project I/O |
mutate Document (send results back to main) |
| Audio callback (engine) | current render graph pointer, transport position | allocate, lock, block, do I/O, log, call Rust |
| MIDI input (engine backends) | nothing: each open port pushes its messages into its own lock-free queue | block, call Rust |
Hand-off mechanisms:
- Session snapshots. After every
Documentrevision change, the main thread builds aSessionSnapshot(pure data, frames at engine rate) and callsse_session_publish. The engine copies it, builds an immutable render graph off the audio thread, and swaps it in with an atomic pointer exchange. Retired graphs are reclaimed by the non-RT side (never freed in the callback). - Transport commands go through a bounded lock-free queue drained at block start, so they're sample-accurate to the block boundary.
- Readouts (transport position, meters, callback stats) are atomics written by the callback and polled by the UI each frame.
- MIDI input crosses from the platform's MIDI thread to the callback through one SPSC queue per
port; the callback routes it to instrument tracks and, while recording, writes what it delivered
into a capture ring the main thread drains (
engine/README.md› MIDI input).
The audio callback never sees Project, tempo or ticks. All musical-time maths happens in
dstudio_core::snapshot.
dstudio_core::Command is the single mutation path for the UI, keyboard shortcuts, scripting, tests and
the AI assistant:
- Validation in
apply(ranges, existence, kind compatibility, asset bounds). On error the project is unchanged. Batches are atomic and roll back on the first failure. - Undo/redo:
applyreturns the exact inverse. Ids are assigned before execution, so redo reproduces identical ids. Ids are never recycled. - Coalescing: continuous gestures (fader/pan/tempo drags) merge into one undo step within 750 ms per target.
- Labels for "Undo ⟨action⟩" menu titles.
- Serialisation (
{"op":"set_tempo","bpm":128}) makes commands usable as AI tool calls and scripts, and replayable in tests.
- Project = directory
Name.dsproj/containingproject.json{format, schema_version, saved_with, project}. Atomic save (temp + fsync + rename). - Media referenced externally by project-relative and absolute path. On load the relative path wins (project moved with its media), then the absolute path, and anything missing is reported.
- Schema migrations:
persist::migrate(from, value)upgrades step by step. Newer-than-supported files are rejected rather than mis-read. - SQLite (planned) is for the sample-library index, analysis caches and plugin scan results: data that is large, query-heavy and rebuildable. The project document stays JSON so it diffs well, merges in VCS, and is easy to inspect and repair.
- Tools exposed to the model = JSON schemas generated from
Commandplus read-only query tools (list tracks, describe selection, transport state). - Assist mode: model output →
Command(deserialised) → validation → preview/confirm policy →Document::execute(cmd, Origin::Assistant)→ one undo step per assistant turn (aBatch). - Teach mode ("Point" in the UI): the model may only return highlight directives
(stable UI element ids) and explanations. Any
Commandit returns is rejected. - Runs out of process or async. The DAW works fully offline. AI never touches engine memory.
Status per platform, what CI covers and what is untested on real hardware:
engine/README.md › Platforms.
- Shared code (core, engine DSP and graph, UI) has no OS-specific dependencies. Platform code is
isolated in
engine/src/platform/*(C++) and behind#[cfg]in Rust (the macOS transparent-titlebar winit hook indstudio-app, per-OS folders inprefs.rs/devices.rs, link libraries indstudio-engine/build.rs). - OS layer:
engine/src/platform/os.{hpp,cpp}: UTF-8 everywhere at the interface (wide Win32 APIs underneath:_wfopen,CreateProcessW,GetModuleFileNameW,CommandLineToArgvW), environment, and aChildProcessabstraction (CreateProcessW / posix_spawn) used by the out-of-process plugin scanner and its tests. - Audio, behind one
AudioDeviceinterface:- macOS: Core Audio (AUHAL; private aggregate device for duplex).
- Windows: WASAPI shared mode, event-driven, float32, converted to the engine rate by
AUTOCONVERTPCM; duplex through a separate capture client and a drift-tolerantFrameRing. ASIO is future work (separately licensed SDK, not added). - Linux: PipeWire playback/capture streams (same
FrameRingduplex). JACK is future work for jackd-only systems (PipeWire already serves JACK clients). - Real-time thread priority: Core Audio's IO thread; MMCSS "Pro Audio" on the WASAPI thread; PipeWire's data thread (RTKit / rt module).
- MIDI input: Core MIDI (macOS), the multimedia
midiIn*API (Windows), the ALSA sequencer (Linux), behind oneMidiBackendinterface. - Plugins: AU (macOS only), VST3 and CLAP everywhere; libraries loaded with CFBundle /
LoadLibraryExW/dlopen, standard per-OS folders, VST3 class ids stored in the canonical text form on every OS. Editors: NSWindow (macOS), a top-level HWND hosting the plugin's child window (Windows), an X11 window the plugin embeds into (Linux; XWayland on Wayland desktops), with a host run loop for the plugins' fds and timers (src/platform/run_loop.cpp, run fromse_plugin_idle). - App: Slint (winit backend) + wgpu 30 build on all three; Linux needs the X11/Wayland, xkbcommon, fontconfig, udev, PipeWire and ALSA development packages (see the CI workflow).
- CI (
.github/workflows/ci.yml): one job per OS, all on GitHub-hosted runners (macos-latest,windows-latest,ubuntu-latest; no audio device, so device tests skip). Real-hardware audio tests are run by hand on a Mac. Each job builds the engine with warnings as errors and runs ctest,cargo build/cargo test --workspaceand the app self-test (engine/README.md› Platforms).
- No JUCE in milestone 1. The engine uses direct Core Audio plus a hand-written WAV reader/writer and resampler: fewer dependencies, full control of RT behaviour, faster builds. JUCE modules (or direct SDKs: VST3 SDK, CLAP headers, AU via AudioToolbox) will be evaluated when plugin hosting starts. The C ABI keeps this choice invisible to Rust.
- Hand-written FFI instead of bindgen, to avoid a libclang build dependency. A layout test guards against drift.
- UI rendering approach: see ADR 0001 (Slint/wgpu interop spike).