Developer guide

This guide is for people who build music applications with SHUFFLE: C++ developers, web and front-end developers, and anyone building with an AI coding assistant. If you want to change the framework itself, read AGENTS.md and the architecture instead.

What SHUFFLE is

• A set of pure C++20 libraries (the cores, in core/) that hold the logic of music software: time and tempo maps, timecode, set lists, cue lists, routing by name, MIDI, OSC, DSP blocks, a synthesizer, an audio graph, file formats, loudness, a command layer, view models for a UI.
• Adapters (in adapters/) that connect the cores to real devices, files, sockets and plugins without JUCE; adapters on JUCE 9 and Tracktion Engine (devices, a webview, songs as Edits) come from the shuffle_juce satellite.
• One way to change state: every user action is a command with a schema. A button, a MIDI pedal, an OSC message, a web page and an AI model all send the same commands and read the same snapshots.

What SHUFFLE is not

• Not an application. You write the main(): SHUFFLE gives you objects to build and wire (the composition root).
• Not a GUI toolkit. A UI is either your toolkit drawing core/ui_model view models, or a web page over the UI bridge.
• Not a monolith with global state. There are no singletons; nothing starts until you create it (why).
• Not finished. Many parts are done and tested, others are specified and waiting. The roadmap has the status of every module; this guide marks what is coming instead of describing it as ready.

The tutorials and the glossary are also in Italian.

Three paths

You are…	Start with	Then
a C++ developer writing a native app, a tool or a plugin-style processor	Install and first build, Your first app	Headless DSP, Choose backends
a web or front-end developer drawing the interface in HTML, CSS and JavaScript	Install and first build, A set list with a GO button	Read state, Theme your UI
building with an AI assistant	Building with an AI assistant	Add a command, Specs and requirement IDs

How these pages are organised

The guide follows four kinds of documentation. Pick the kind that matches what you need right now.

Kind	Use it when you want to…	Pages
Tutorials	learn by doing, step by step, from nothing to a working program	1 Install · 2 First app · 3 Web set list · 4 Headless DSP · 5 AI assistant
How-to guides	get one task done	Choose backends · Add SHUFFLE to a JUCE project · Add a command · Read state · MIDI controller and learn · Named outputs · Play and record files · Host plugins · Sync with other devices · Cue lists and show control · Network audio and redundancy · Loudness · Synth instruments · Native UI from view models · Ship on mobile and the web · Real-time rules · Errors as values · Theme your UI · Test your app · Licences and notices
Concepts	understand why the framework is shaped this way	Cores, ports, adapters · Commands and snapshots · Threads and real time · Time · Specs and requirement IDs · Why no globals · Compared with a monolithic framework
Reference	look something up	Reference index · Glossary

The rule of thumb

Every snippet in the tutorials comes from a program that is built and run: the examples, which CI runs on every change, or a project generated by cmake/ShuffleEngineNewProject.cmake. When this guide and an example disagree, the example is right; please report the page.