DX7 FM Synthesis Library for Swift
M2DX-Core is an FM synthesis library that reproduces the Yamaha DX7 sound engine in pure Swift. All code is originally implemented based on the DX7's published hardware specifications and the mathematical definition of FM synthesis.
Phase 2 Complete (2026-02-16) — The library extraction and clean room implementation is complete. All synthesis components, tests, and CI pipeline are functional. The next phase will focus on public API design and SPM release preparation.
- MIT License — Free for commercial and non-commercial use, no restrictions
- Swift 6 — Strict concurrency, value semantics, zero-allocation audio rendering
- MIDI 2.0 Native — 16-bit velocity, 32-bit CC, per-note controllers (MPE-compatible)
- Apple Accelerate — Hardware-accelerated DSP using vDSP (SIMD optimization)
- Lock-Free Architecture — Parameter changes delivered via atomic SPSC ring buffer
- Bit-Accurate DX7 Mode — Int32 fixed-point arithmetic reproduces the original OPS chip
- Clean Float32 Mode — Modern floating-point engine for extensibility
- iOS 18.0+ / macOS 15.0+
- Swift 6.0+
- Xcode 16.0+
# Clone the repository
git clone https://github.com/yourusername/M2DX-Core.git
cd M2DX-Core
# Build the library
swift build
# Run tests
swift test
# Run tests with verbose output
swift test --verboseAll 107 tests should pass. Performance benchmarks may vary depending on your hardware (x86_64 vs ARM).
The library includes comprehensive test coverage across 8 test suites:
| Test Suite | Tests | Coverage |
|---|---|---|
| TableTests | 11 | Sin/Exp2 precision, frequency table, pitch bend, scaling curves |
| EnvelopeTests | 10 | 4-stage ADSR, rate=99 fast attack, noteOff silence verification |
| AlgorithmTests | 32 | All 32 DX7 algorithms carrier count, feedback, bus routing |
| WaveformTests | 8 | renderBlock output, silent voice, feedback modulation effects |
| ConcurrencyTests | 3 | SnapshotRing stress test, SynthEngine concurrent note on/off |
| PerformanceTests | 2 | 16 voices × 512 frames rendering benchmark |
| ReferenceTests | 10 | Operator-level DEXED comparison (ScaleRate, ScaleVelocity, ScaleLevel, exp2, EG, algorithms) |
| VoiceComparisonTests | 14 | Voice-level waveform comparison against DEXED (INIT VOICE, algorithms, feedback, velocity, rate scaling, KLS, detune, E.PIANO) |
Run tests with:
swift test # Run all tests
swift test --verbose # Verbose output with test names
swift test --filter Table # Run only TableTestsM2DX-Core provides two synthesis modes:
| Mode | Arithmetic | Precision | Use Case |
|---|---|---|---|
| DX7 | Int32 fixed-point (Q24/Q30) | Bit-accurate to OPS chip | Authentic reproduction |
| Clean | Float32 | ~24-bit mantissa | Extensibility, custom waveforms |
"Bit-Accurate Soul, Modern Body"
- Soul: The DX7's sonic character — log-domain arithmetic, envelope curves, feedback averaging, 32 algorithm routings — is reproduced at bit-level accuracy.
- Body: Memory management, thread model, and API design are optimized for Apple platforms with modern Swift paradigms.
All lookup tables and computation kernels are independently implemented:
- Sin / Exp2 Tables: Generated at compile time from mathematical functions
- Velocity, KLS, EG Rate Tables: Derived from FM synthesis definitions and publicly available hardware specifications
- 32 Algorithm Routing: Encoded from Yamaha DX7 operator connection topology
- Zero-Allocation: No
malloc,retain, orreleasein the audio render loop - Lock-Free SPSC Ring Buffers: UI-thread parameter changes and MIDI events delivered without blocking the audio thread
SnapshotRing<T>: Parameter snapshot delivery (UI → Audio)SPSCRing<T>: MIDI event FIFO queue (UI → Audio, preserves event order)
- Pre-allocated Voice Arrays: All voice structures and scratch buffers allocated at initialization
- Fixed-Size Tuples: Parameter snapshots use fixed-size tuples instead of dynamic arrays to prevent heap deallocation on audio thread
- Caller-Provided Scratch Buffers: DSP operations use pre-allocated scratch space to eliminate internal allocations
- No Locks: All cross-thread communication uses atomic operations (
Synchronization.Atomic) instead of NSLock/pthread_mutex
Apple Accelerate (vDSP) is used for batch DSP operations:
- FIR downsampling (2x oversampling decimation)
- Int32 → Float conversion (DX7 Q24 block output)
- Voice mixing (scale + add, stereo panning)
- Gain application (master volume)
- Hard clipping (output limiter)
| Mode | Slots | Voices/Slot | Description |
|---|---|---|---|
| Single | 1 | 16 | Standard DX7 |
| Dual | 2 | 8 | Layer two patches |
| Split | 2 | 8 | Keyboard split |
| TX816 | 8 | 2 | 8-module monster synth |
| Dependency | Version | Purpose |
|---|---|---|
| Synchronization (stdlib) | Swift 6.0+ | Lock-free atomic operations for SPSC ring buffer |
| Accelerate (system) | — | vDSP batch DSP operations (mixing, clipping, conversion) |
Note: This library uses Swift 6.0's built-in Synchronization module for atomic operations, eliminating the need for external dependencies like swift-atomics.
MIT License — See LICENSE for details.
See TODO.md for the complete roadmap.
- Swift Package with Swift 6.0 strict concurrency
- Self-generated lookup tables (sin, exp2, frequency, scaling)
- Lock-free
SnapshotRing<T>usingSynchronization.Atomic - DX7 presets, algorithms, and SysEx parser
- Full synthesis engine (envelope, operator, voice, polyphony)
- Accelerate-based DSP (downsampler, voice mixer)
- 107 tests across 8 test suites (including voice-level DEXED comparison)
- GitHub Actions CI pipeline
- Bit-exact waveform verification against DEXED reference implementation
- Public API design and documentation
- DocC documentation for all public types
- API stability guarantees
- MIT license headers
- Getting-started tutorial and code examples
- 8-slot voice routing (2-16 voices per slot)
- Keyboard split/layer logic
- Macro controls (brightness, attack, sustain)
- AudioUnit v3 wrapper
- docs/API.md — Complete public API reference
- docs/proposal.md — Full technical specification and design philosophy
- TODO.md — Detailed roadmap and task list
- CHANGELOG.md — Version history
This project is currently in early development. Contributions will be welcomed after the Phase 3 SPM release.
This library is developed as part of the M2DX synthesizer app.
M2DX-Core — Bringing the legendary DX7 sound to modern Swift development.