Open-source DJ software with stem-based mixing and neural audio separation.
Mesh lets you mix music by controlling individual elements (vocals, drums, bass, instruments) independently. Import any audio file and Mesh automatically separates it into stems using AI — no external tools required.
Mesh is a DJ software suite with two applications:
| Application | Purpose |
|---|---|
| mesh-cue | Prepare your music library — import tracks, separate stems, analyze BPM/key, edit beat grids, organize playlists |
| mesh-player | Perform live — 4-deck mixing with stem control, beat sync, effects, and MIDI controller support |
Traditional DJ software mixes complete stereo tracks. Mesh gives you control over each element:
- Mute the vocals for an instrumental breakdown
- Solo the drums during a transition
- Swap the bassline from one track with another
- Apply effects to individual stems
Mesh also includes built-in stem separation — drop any MP3, FLAC, or WAV file and it's automatically split into 4 stems using the Demucs neural network.
- Automatic stem separation — Import regular audio files; AI separates into Vocals, Drums, Bass, and Other
- BPM and key detection — Automatic analysis with configurable tempo ranges. Advanced mode uses the Beat This! neural network (ISMIR 2024) for SOTA beat tracking that eliminates half-tempo errors common with DnB and fast tempos. Simple mode uses Essentia's classic algorithm
- Beat grid editing — Fine-tune beat markers, set downbeats, adjust BPM with visual feedback
- 8 hot cues per track — Set, edit, and color-code cue points
- Stem linking — Prepare mashups by linking stems from different tracks (e.g., vocals from track A over instrumentals from track B)
- ML-enhanced audio analysis — Automatic genre classification and mood tagging using neural network models (EffNet + Discogs400). Vocal/instrumental detection via stem energy analysis. Optional arousal/valence estimation for smarter energy-aware suggestions
- Playlist management — Organize tracks into playlists with drag-and-drop
- USB export — Sync playlists to USB drives for portable performance
- 4-deck architecture — Load and mix up to 4 tracks simultaneously
- Per-stem control — Mute, solo, and adjust volume for each stem independently
- Automatic beat sync — Tracks phase-lock automatically when you press play
- Automatic key matching — Pitch-shift tracks to match harmonically (Camelot wheel)
- Stem slicer — Real-time remixing by rearranging slice playback order
- Effects — DJ filter, delay, reverb, plus CLAP plugins and Pure Data patches with per-stem routing
- MIDI controller support — Configure any controller with MIDI Learn wizard
- Smart suggestions — AI-powered track recommendations based on what's currently loaded. Finds harmonically compatible tracks using audio fingerprint similarity, key matching, BPM proximity, and perceptual arousal. An energy direction fader lets you steer suggestions toward higher-energy or cooler tracks. Choose between two key matching algorithms in Settings:
- Camelot — Classic DJ wheel with hand-tuned transition scores
- Krumhansl — Perceptual key distance based on music psychology research, better at rating cross-mode transitions (e.g., C major to C minor)
- Vertical waveform layout — Alternative display mode where time flows top-to-bottom instead of left-to-right. Four overview columns cluster in the center with zoomed waveforms flanking them on each side, providing a chronological timeline view across all decks simultaneously. Switch between Horizontal and Vertical layouts in Settings → Display → Waveform Layout — takes effect instantly without restart
- Auto-gain — Tracks are loudness-normalized so volumes are consistent
- Track tags — Color-coded tag pills in the browser for genres, moods, or custom labels. Suggestion results include auto-generated reason tags (see below)
- Zero-dropout loading — Load new tracks while playing without audio glitches
- High-quality time stretching — Tempo changes without pitch artifacts
- Master bus protection — Built-in limiter and clipper prevent distortion and protect your speakers, even when mixing hot
- Low-latency audio — JACK on Linux, WASAPI on Windows. Real output pipeline latency is measured from CPAL/JACK timestamps and used to compensate beat-snap decisions, so hot cues and synced starts land on the beat the user actually heard. Timing-critical MIDI commands (play, cue, hot cue, beat jump) bypass the UI tick loop and go directly to the audio engine via a dedicated lock-free ringbuffer
- Professional routing — Separate master and cue outputs for headphone monitoring
| Package | Platform | Description |
|---|---|---|
mesh-cue_amd64.deb |
Linux (Debian/Ubuntu) | Full DJ application with stem separation (CPU) |
mesh-cue-cuda_amd64.deb |
Linux (Debian/Ubuntu) | Full DJ application with NVIDIA CUDA acceleration |
mesh-cue_win.zip |
Windows 10/11 | Full DJ application with DirectML GPU acceleration |
mesh-player_amd64.deb |
Linux (Debian/Ubuntu) | Lightweight stem player |
mesh-player_win.zip |
Windows 10/11 | Lightweight stem player |
# Standard build (CPU stem separation)
sudo dpkg -i mesh-cue_amd64.deb
# OR with NVIDIA GPU acceleration
sudo dpkg -i mesh-cue-cuda_amd64.deb
# Optional: lightweight player only
sudo dpkg -i mesh-player_amd64.debRequirements:
- Ubuntu 22.04+, Debian 12+, Pop!_OS 22.04+, or similar
- PipeWire or JACK audio server
- For CUDA build: NVIDIA driver 525+ and CUDA 12
- Download and extract
mesh-cue_win.zipormesh-player_win.zip - Run
mesh-cue.exeormesh-player.exe
Requirements:
- Windows 10 or 11
- DirectX 12 capable GPU for accelerated stem separation (optional — falls back to CPU)
Launch mesh-cue and import your tracks:
Option A: Automatic Stem Separation
- Copy audio files (MP3, FLAC, WAV) to
~/Music/mesh-collection/import/ - Click Import → Select "Mixed Audio" mode
- Tracks are automatically separated into stems, analyzed, and added to your collection
Note: Stem separation requires ~4GB RAM per track and takes 2-5 minutes on CPU, or 15-30 seconds with GPU acceleration.
Option B: Pre-Separated Stems If you've already separated stems using Demucs, UVR, or similar tools:
- Name files as
Artist - Track_(Vocals).wav,Artist - Track_(Drums).wav, etc. - Click Import → Select "Pre-separated Stems" mode
In mesh-cue, load a track to:
- Verify BPM detection and adjust if needed
- Set hot cues at key moments (drops, breakdowns, vocals)
- Fine-tune the beat grid alignment
- Optionally link stems from other tracks for mashups
Launch mesh-player, load tracks onto the 4 decks, and start mixing:
| Control | Function |
|---|---|
| Play/Cue | CDJ-style transport (hold cue to preview) |
| Stem buttons | Mute individual stems |
| Sync | Automatic beat alignment |
| Key | Automatic harmonic matching |
| Slicer | Enter slice mode for real-time remixing |
Mesh works with any MIDI controller. Use the MIDI Learn wizard to map your hardware:
mesh-player --midi-learnThe wizard guides you through mapping transport controls, performance pads, mixer faders, and browser navigation. Mappings are saved to ~/.config/mesh-player/midi.yaml.
Supported devices:
| Device | Protocol | Features |
|---|---|---|
| Allen & Heath Xone K3 | MIDI | Rotary encoders, buttons, note-offset RGB LEDs (red/amber/green) with beat-synced pulsing |
| Native Instruments Traktor Kontrol F1 MK2 | HID | 4x4 RGB pad grid, encoders, faders, full-color LED feedback |
| Pioneer DDJ-SB2 | MIDI | Profile included |
Any class-compliant MIDI controller works via the Learn wizard. HID devices require a driver (currently F1 only). Controllers with note-offset LEDs (Xone K series) are auto-detected for correct color handling.
For controllers with limited buttons (e.g., two Kontrol F1s), the MIDI Learn wizard supports:
- Momentary mode overlays — Hold a mode button to temporarily switch pads to Hot Cue or Slicer mode. Release to return to the default performance mode (stem mutes, transport). Per-side mode buttons control two decks each (left side = decks 1+3, right side = decks 2+4).
- Dual browse encoders — Map separate left/right browse encoders for independent deck browsing.
- State-aware RGB feedback — HID pads show distinct colors per function (green=play, orange=cue, amber=hot cue, cyan=slicer, per-stem colors for mutes) and automatically switch color schemes when mode buttons are held.
Experimental: Stem separation quality may vary. GPU acceleration is untested on some hardware.
Mesh uses Demucs (Meta AI) for neural stem separation:
| Setting | Options | Effect |
|---|---|---|
| Model | Standard / Fine-tuned | Fine-tuned has ~1-3% better quality |
| Shifts | 1-5 | More shifts = better quality, slower processing |
Performance:
| Hardware | Time (4-min track) |
|---|---|
| CPU (8-core) | 3-5 minutes |
| NVIDIA RTX 3070 | 20-30 seconds |
| NVIDIA RTX 4090 | 10-15 seconds |
Configure in Settings → Separation.
Mesh supports custom audio effects written in Pure Data, a visual programming language for audio. Create your own filters, delays, distortions, or even neural audio effects like RAVE.
Place effects in ~/Music/mesh-collection/effects/ and they'll appear in the effect picker.
See examples/pd-effects/ for templates, documentation, and working examples including a RAVE neural percussion processor.
Mesh supports CLAP (CLever Audio Plugin) — the modern open-source plugin standard. Load any Linux CLAP plugin as a stem effect:
- LSP Plugins — Professional compressors, EQs, reverbs, gates
- Dragonfly Reverb — Algorithmic room and plate reverbs
- Airwindows — Hundreds of boutique effects
- BYOD, ChowTapeModel — Guitar amp sims and tape saturation
Plugin locations:
~/.clap/ # User plugins
/usr/lib/clap/ # System plugins
Install CLAP plugins from your distro's package manager or download from plugin developers. Plugins appear automatically in the effect picker under their categories.
When you toggle suggestions on in the collection browser, Mesh analyzes the tracks loaded on your decks and recommends what to play next. The system combines nine scoring factors:
| Factor | What It Measures |
|---|---|
| Audio similarity | HNSW vector search on 16-dim audio fingerprints (rhythm, harmony, energy, timbre) |
| Harmonic compatibility | Key transition safety via Camelot wheel or Krumhansl perceptual model |
| Key energy direction | Emotional impact of the key transition (semitone up = +0.70, tritone = -0.80) |
| Genre-normalized aggression | Per-genre z-score normalized intensity — answers "how aggressive is this track for its genre?" so house tracks can compete with DnB |
| Danceability | ML-derived danceability alignment with the energy fader direction |
| Approachability | ML-derived music approachability alignment with the energy fader direction |
| Tonal/timbre contrast | At extremes, rewards opposite tonal and timbre characteristics to the seed |
| Production match | Prefers candidates with similar acoustic/electronic production character |
| Tempo proximity | BPM distance from currently playing tracks |
The fader steers what kinds of tracks are recommended. At center, audio similarity dominates for safe harmonic matches. At extremes, audio similarity drops to zero and genre-normalized aggression becomes the dominant signal (30%), with key harmony relaxing from 25% to 15% as the user accepts harmonic risk in exchange for energy direction:
| Center | Extreme | |
|---|---|---|
| Audio similarity | 42% | 0% |
| Key compatibility | 25% | 15% |
| Key energy direction | 15% | 22% |
| Genre-normalized aggression | 0% | 30% |
| Danceability | 0% | 10% |
| Approachability | 0% | 6% |
| Tonal/timbre contrast | 0% | 4% |
| Production match | 3% | 3% |
| BPM proximity | 15% | 10% |
Each key transition has a research-calibrated emotional energy direction. The fader both steers which transitions are preferred and relaxes the harmonic filter to allow dramatic key changes:
- Center — Strict: same key, adjacent, relative, diagonal
- Right — Progressively prefers energy-raising transitions (boost, mood lift, semitone up)
- Left — Progressively prefers energy-cooling transitions (cool, darken, semitone down, tritone)
Each suggestion shows a colored tag pill (green/amber/red) with a directional arrow (▲ raise / ▼ cool / ━ same key) indicating the harmonic relationship.
Two algorithms are available in Settings → Display → Key Matching:
| Model | Description |
|---|---|
| Camelot (default) | Classic DJ wheel — hand-tuned scores for each transition category. Well-understood, predictable. |
| Krumhansl | Based on Krumhansl-Kessler (1982) music psychology research. 24×24 perceptual key distance matrix from listener probe-tone ratings. Better at cross-mode transitions. |
See documents/similarity-search.md for the full technical documentation including the scoring pipeline, all transition types with emotional impact descriptions, the adaptive filter thresholds, and parameter reference.
- 4-deck stem mixing with mute/solo
- Automatic BPM and key detection
- Beat grid editing and alignment
- Auto beat sync between decks
- Auto key matching (harmonic mixing)
- Stem slicer with customizable presets
- Stem linking for mashups
- Built-in Demucs stem separation
- GPU acceleration (CUDA/DirectML)
- MIDI and HID controller support with learn wizard
- USB export for portable performance
- Track similarity search (audio fingerprinting)
- Smart suggestions with energy direction control
- ML genre classification and mood tagging (EffNet/Discogs400)
- ML beat detection (Beat This! ONNX model — no half-tempo errors)
- Auto-gain loudness normalization
- Vertical waveform layout (top-to-bottom timeline view)
- Master bus limiter and clipper (PA protection)
- Effects: filter, delay, reverb
- Pure Data effect patches (custom DSP via PD)
- CLAP plugin hosting (LSP, Dragonfly, Airwindows, etc.)
- RAVE neural audio effects (via nn~ external)
- Multiband effect container with macro knob routing
- Session history and set reconstruction
- On-the-fly stem linking during performance
- Slicer morph knob for preset banks
- Real-time LUFS normalization per stem
- macOS support
- Recording to file
~/Music/mesh-collection/
├── import/ # Drop files here for import
├── tracks/ # Your stem library
├── playlists/ # Playlist folders (symlinks)
└── config.yaml # Settings
Click the gear icon in mesh-cue to configure:
| Setting | Description |
|---|---|
| BPM Range | Set min/max tempo for genre-specific detection (e.g., DnB: 160-190) |
| Beat Detection | Simple (Essentia) or Advanced (Beat This! ML model) |
| Separation Model | Standard or Fine-tuned Demucs |
| Separation Shifts | Quality vs. speed tradeoff (1-5) |
| Target Loudness | LUFS target for auto-gain (-14 LUFS default) |
Customize stem colors in ~/.config/mesh-player/theme.yaml:
stems:
vocals: "#33CC66" # Green
drums: "#CC3333" # Red
bass: "#E6604D" # Orange
other: "#00CCCC" # CyanNo audio output:
- Linux: Ensure JACK or PipeWire is running (
pw-jack mesh-playerfor PipeWire) - Windows: Check audio device in system settings
Audio dropouts:
- Increase buffer size in your audio server settings
- Close other audio applications
"CUDA not available" on Linux:
- Install NVIDIA driver 525+ and CUDA 12 toolkit
- Use the
mesh-cue-cuda_amd64.debpackage
Separation quality issues:
- Use higher quality source files (FLAC/WAV over low-bitrate MP3)
- Increase "Shifts" setting in Settings → Separation
Controller not detected:
- Check connection and permissions
- On Linux: ensure user is in
audiogroup
For developers:
# Clone and enter dev environment
git clone https://github.com/yourusername/mesh.git
cd mesh
nix develop
# Build
cargo build --release
# Run
cargo run -p mesh-player
cargo run -p mesh-cueSee ARCHITECTURE.md for technical details on the audio engine, real-time architecture, and signal flow.
Mesh can run standalone on an ARM64 single-board computer — no laptop required. The target hardware is an Orange Pi 5 Pro (RK3588S, 8 GB RAM, ~$80) with a PCM5102A I2S DAC on the GPIO header for master audio output and the onboard ES8388 codec for headphone cue. Total core BOM is around $112.
The embedded setup runs NixOS with mesh-player in a Wayland kiosk (cage compositor), booting directly into fullscreen performance mode. Tracks are loaded from a USB 3.0 stick — the same workflow as CDJs.
| Component | Role |
|---|---|
| Orange Pi 5 Pro 8GB | RK3588S SoC, WiFi 5, USB 3.0 |
| PCM5102A I2S DAC | Master output via GPIO (112 dB SNR) |
| ES8388 onboard codec | Cue/headphone output (3.5mm TRRS) |
| cage + mesh-player | Wayland kiosk, fullscreen on boot |
- Download the SD image from GitHub Releases (look for
sdimage-*tags) - Flash to microSD:
zstdcat nixos-sd-image-*.img.zst | sudo dd of=/dev/sdX bs=4M status=progress - Boot — NixOS starts mesh-player in kiosk mode automatically
- Update — the device pulls pre-built packages from the binary cache, never compiles:
sudo nixos-rebuild switch --flake github:dataO1/Mesh/v0.9.0#mesh-embedded --no-write-lock-file
CI builds mesh-player natively on a free GitHub Actions ARM runner and publishes the binary cache to GitHub Pages. SD images are uploaded to Releases with hash-based deduplication (only rebuilt when the NixOS configuration changes).
See documents/embedded-setup.md for the full guide covering hardware wiring, device tree overlays, NixOS configuration, audio routing, deployment workflow, and debugging.
Contributions welcome! Areas where help is appreciated:
- Audio DSP — Effects, EQ implementations
- UI/UX — Waveform rendering, accessibility
- Testing — Integration tests, audio quality verification
- Platform support — macOS builds
Please open an issue to discuss major changes before submitting a PR.
AGPL-3.0 — see LICENSE for details.
Uses Essentia (AGPL-3.0) and Demucs for audio analysis and stem separation. Genre and mood classification models from the Essentia model hub (CC BY-NC-SA 4.0).
- Demucs — Neural stem separation
- signalsmith-stretch — Time stretching
- Essentia — Audio analysis (key, LUFS, BPM fallback)
- Beat This! — ML beat and downbeat tracking (ISMIR 2024)
- iced — GUI framework
- JACK — Professional audio routing
Mesh is under active development. Star the repo to follow progress!