Brandon ThomasandClaude Opus 5.5
330a698397
* Progress docs to the craftrules standard; full re-measure against Pro Tools 2026.4.1 Stage: alpha. Menu breadth 482/512 (94.1%, measured), feature breadth ~70%, ready for real work ~40%; ~350-570 agent-hours to beta, ~950-1,450 to full parity, calibrated on this repo's PR history. - ROADMAP.md rewritten: stage banner, two numbers, dimension/feature/language tables - docs/target-app-parity.md: authoritative assessment (area table moved from ROADMAP) - docs/gaps.md: 22 ranked gaps with evidence and estimates - docs/roadmap.md: milestones, current focus, beta plan - docs/ui-, file-format-, hardware-, plugin-, localization-parity.md: new checklists - docs/parity.md -> docs/parity-checklist.md (generated by cargo xtask parity) - architecture.md: video, vst3-host, au-host crates; device I/O limits Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Stage: pre-alpha under the core-workflow gate Add the alpha gate to docs/roadmap.md: interface recording at a chosen buffer size, MIDI recording, and session interchange with Pro Tools fail, so the stage moves from alpha to pre-alpha (~5 points and ~110-180 agent-hours to alpha). Mark the alpha blockers in docs/gaps.md; update ROADMAP.md, target-app-parity.md and README. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Add mainstream-practitioner and essentials-user readiness numbers Mainstream practitioner ~36% (weekly-area depth 50.6% x 0.90 interaction x 0.92 stability x 0.85 file exchange) and essentials user ~57% (core-feature depth 72.4% x 0.90 launch/stability x 0.90 discoverability x 0.97 files), with written weights, discounts and GitHub user evidence. Full ready-for-real-work checked against its written dimension weights (40.6%); unchanged at ~40%, stage unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Readiness by audience: hours to ~95% for full, mainstream and essentials Full ~40% / 950-1,450 h, mainstream ~36% / 380-600 h, essentials ~57% / 110-200 h, calibrated on this repo's PR history. The full number is already an additive weighted sum over the written dimension table; method unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
4.3 KiB
Architecture
Last reviewed: 2026-10-10 · Last updated: 2026-10-10 · Change: minor (crate diagram brought up to date: video, vst3-host, au-host; device I/O limits) · Target: Avid Pro Tools Ultimate 2026.4.1
SoundCraft is a Cargo workspace of small crates with enforced layering (cargo xtask layers).
Nothing below the UI knows about egui, so the interface can be replaced.
L0 time audio-io midi video (standalone: no workspace deps)
L1 dsp clap-host vst3-host au-host (plugins; the three hosts are the only crates
allowed `unsafe`, confined to their FFI modules)
L2 model (the session document)
L3 mix (the mix engine)
L4 engine playback (commands, undo, I/O · audio devices)
L5 automation (MCP server, control-channel client)
L6 ui-egui (the user interface)
apps: soundcraft (desktop) · soundcraft-cli · soundcraft-web (wasm)
The document
soundcraft_model::Session is plain data (serde): tracks with playlists of clips, mixer state
(inserts, sends, routing, automation lanes), tempo and meter maps, memory locations, groups,
busses, and EditState (selection, tools, modes, view flags). Decoded audio lives in a
SourcePool of Arcs that is not serialised; cloning a session is cheap. Sessions save as
.scraft JSON plus an Audio Files/ folder.
Commands and undo
Every user action is a CommandSpec (id, label, menu path, shortcut, params doc, enabled, run)
registered in crates/engine/src/cmd/. Engine::execute(id, params) runs it, catches any escaped
panic, and pushes an undo snapshot (the previous Arc<Session>) when the document changed.
Continuous gestures use execute_merged so a fader drag is one undo step. Menus are built from
the incumbent's menu catalog (crates/engine/catalog/menus.txt); a menu item lights up when a
command has the same menu path and label (or an alias maps it), which also drives the parity
report.
Audio
soundcraft_mix::MixEngine::render(session, pos, frames, out) renders one block: clips (gain,
fades, clip effects) → trim → inserts → pre-fader sends → fader/mute (automation, VCA, trim
automation) → post-fader sends → pan → busses → aux inputs → master faders. Independent strips
process in parallel; plugin delay compensation aligns every path. The same engine renders
bounces offline (render_range) and realtime playback (soundcraft_playback::Player, which owns
it on the audio thread and receives new session snapshots through a channel).
Device I/O today is the system's default output and default input device, opened as two
separate cpal streams; the mix renders 512-sample blocks and resamples to the device rate when
they differ. There is no device or buffer-size selection, no ASIO, and no MIDI device layer yet
(see hardware-parity.md). Sources are decoded whole into the SourcePool
and recordings are captured in memory until stop.
soundcraft-video holds our own H.264, ProRes and Motion JPEG decoders and the ISO-BMFF demuxer
for the video track. Hosted plugins (clap-host, vst3-host, au-host) are scanned, created and
destroyed off the audio thread; only process runs on it.
The cpal callbacks mark their thread (soundcraft_playback::mark_audio_thread). Code that may run
there can ask on_audio_thread() before doing anything that blocks; the desktop app's logger does,
so a log:: record from the audio thread (a stream error, a full synth event queue, a hosted
plugin's failed process, a CLAP plugin's own log call) is kept without waiting and written later
by the UI thread (see README › Logs).
Agent control
The desktop app's control channel (JSON lines over TCP) exposes engine commands, inspection,
synthetic input and screenshots; soundcraft-cli mcp wraps either a headless engine or a running
app as an MCP server. See control-protocol.md and mcp.md.
Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-10 | minor | Added video, vst3-host and au-host to the layer diagram; documented device I/O limits and in-memory media |
| 2026-10-05 | major | First architecture overview |