Specifications

Every domain of shuffle_engine has a behavioural specification in specs/<domain>.md, with numbered requirements (such as TC-R12) and examples as data. Tests cite the requirement IDs, so one search finds the spec, the code and the test of a behaviour:

grep -rn "TC-R12"

Read Specs and requirement IDs for how they are written and used. The specifications live in the repository; each link below opens one on GitHub.

Specification	File	What it covers
Commands — behavioural specification	specs/commands.md	Command descriptors, validation, preview, undo, name resolution, snapshots, schemas and grammars for models, profiles, safety.
Cues — behavioural specification	specs/cues.md	Theatre cue lists, GO and playhead, groups, retrigger rules, fades, panic, wall-clock triggers, quantised launch, grids, scenes.
DSP building blocks — behavioural specification	specs/dsp.md	Smoothing, interpolators, filters, band-limited oscillators, noise, LFOs, ADSR, delays, dynamics, EQ, reverb, distortion, FFT, convolution.
Edit — behavioural specification	specs/edit.md	Non-destructive arrangement editing as commands: tracks, items, takes and comping, fades, stretch, MIDI note editing, quantise and groove, markers and sections, time insert/delete with followers.
Engine — behavioural specification	specs/engine.md	Own audio graph, program swap, latency compensation, deterministic single and parallel scheduling, overload ladder, audio and MIDI item playback, recording, offline render, mapping of every engine port.
Audio and MIDI file formats — behavioural specification	specs/formats.md	Audio file formats and codecs, gapless delay/padding, sample-accurate seeking, metadata, writers, MIDI files.
Looper — behavioural specification	specs/looper.md	Live loops at engine level: input history and retroactive capture, record, overdub, replace, multiply, one level of undo in bounded memory, play modes, quantised sample-accurate actions, mute groups, scenes, device class memory budgets.
Loudness — behavioural specification	specs/loudness.md	BS.1770 / EBU R128 loudness, true peak, PPM/VU meters, stereo field, file QC, normalisation targets.
MIDI — behavioural specification	specs/midi.md	Note gating, panic, triggers and learn, bindings, MIDI Show Control receive, byte-stream parsing, RPN/NRPN, chase, UMP and MIDI 1.0/2.0 translation, sequence playback timing.
Network audio — behavioural specification	specs/netaudio.md	AES67/RAVENNA/ST 2110-30, PTP follower, SDP, SAP, mDNS/RTSP, jitter buffer, ASRC, RTP-MIDI.
OSC — behavioural specification	specs/osc.md	OSC 1.0/1.1 wire format, bundles and time tags, address patterns, scheduled dispatch, UDP/TCP framing.
Redundancy — behavioural specification	specs/redundancy.md	Stream health, ASRC, crossfade failover, synchronous start, command distribution.
Resilience — behavioural specification	specs/resilience.md	Declared fallbacks, health, fault injection.
Routing (audio and MIDI) — behavioural specification	specs/routing.md	Named audio and MIDI endpoints, crosspoint matrices, buses, audition, MIDI routes and hanging-note safety, virtual ports shared with other apps.
Setlist — behavioural specification	specs/setlist.md	Songs, transitions, switch protection, background loading, tempo follow/lead, playhead, loop range, roll-in, metronome.
Show control — behavioural specification	specs/showcontrol.md	Action matrix of MIDI, OSC, UDP/TCP, timecode and internal actions, value curves, MIDI file playback.
Sync — behavioural specification	specs/sync.md	Open tempo/beat/phase sync protocol over wired (PTP), Wi-Fi, BLE, USB, internet relay and MIDI clock.
Synth — behavioural specification	specs/synth.md	Voices and stealing, mono/legato, pedals, MPE receive and send, MIDI 2.0 per-note control, tuning, modulation matrix, sampler, wavetable.
Time — behavioural specification	specs/time.md	Units as types, positions, durations and ranges, tempo maps with key signatures and map edits, section anchors, launch grids, musical count, absolute TAI time, start at a shared instant.
Timecode — behavioural specification	specs/timecode.md	SMPTE arithmetic at eleven rates, MTC and LTC generation to named endpoints, cue conflicts, monitor model, LTC and MTC input with lock and chase rules for followers.
UI bridge — behavioural specification	specs/ui_bridge.md	Web or native declarative UIs over the command catalogue: protocol, topics with deltas, embedded webview, WebSocket and WebAssembly transports, generated TypeScript, real-time data frames, security.
UI layout — behavioural specification	specs/ui_layout.md	The content of a panel: stacks, wrapping rows, grids, overlays, breakpoints; one text-fitting rule (step down, wrap, ellipsis at a word boundary, values ask for space); TextMeasurer port; overlap and clipping checks over a size grid.
UI model — behavioural specification	specs/ui_model.md	Toolkit-free view models and interaction logic: time axis, zoom, snapping, hit-testing, drag gestures as command plans, selection, layout, virtual lists, waveforms, meters, mixer, piano roll, overlays, screens, accessibility.
UI theme — behavioural specification	specs/ui_theme.md	Theme tokens by role, theme families and schemes with computed contrast, component states, paint recipes by part, densities and scaling, motion, window chrome, accessibility, toolkit adapter contract.
UI widgets — behavioural specification	specs/ui_widgets.md	Native widgets as pure C++ drawing into a plain-data draw list: catalogue for music apps (faders, knobs, meters, readouts, lists, timeline…), states, input, accessibility, text fit by ui_layout’s roles and breakpoints, screens as data, Renderer2D and PlatformWindow ports, damage and frame pacing, conformance, performance targets.

New domains start from the template.