Skip to main content
Dub is a Rust audio engine inside a native macOS app. Rust owns the audio thread; Swift owns the UI thread. They talk through lock-free state snapshots and single-producer, single-consumer ring buffers, never through callbacks across threads. This page is the map. The detail lives in the repo, linked below.

The crates

The Swift app lives in apple/Dub/. Waveforms are drawn with Metal.

The audio thread is sacred

A crash or a dropout on stage ends a DJ’s night, so code that runs on the audio thread may not allocate memory, take a lock, make a system call, log, do I/O, call unwrap(), or box a dyn Trait. That’s enforced three ways:
  1. At compile time. Every function reachable from the engine’s render call takes a RealtimeContext token, which can’t leave the audio thread.
  2. In tests. Tests of the render path run under assert_no_alloc; any allocation aborts the test.
  3. In release builds. The same allocator check records the violation instead of crashing.
Work that can’t follow those rules, such as decoding, analysis and the library, runs on other threads. Whole tracks are decoded into memory on load, which is what lets a record play backwards exactly as it plays forwards.

The bridge to Swift

dub-ffi exposes the engine to the app through UniFFI. The Rust signatures are the single source of truth: the Swift bindings are generated from them, packed with the Rust core into DubCore.xcframework. Three objects make up the surface: DubEngine, DubLibrary and DubRipSession. They stay separate so library and disk work never becomes an audio-thread dependency. The bridge carries a contract number, FFI_VERSION. Changing the surface means bumping it, and make docs-check holds the docs to it. The CLI doesn’t go through the bridge. It links the engine directly.

Engineering docs

The full picture is on GitHub:

ARCHITECTURE.md

Threads, messaging, timecode, Thru, the BPM engine and the build.

PRD.md

What Dub is for, and the spec everything else answers to.

LIBRARY-SCHEMA.md

The library’s SQLite schema.

LIBRARY-FORMATS.md

How each DJ app’s library is read and written.

LICENSE-DEPENDENCIES.md

Every dependency’s licence, and why Dub is MIT OR Apache-2.0.

docs/README.md

Which doc to read for which task, including what’s in flight and the lessons learned.