# MIDI, clocks and composition

> Schedule notes, map expression and compose effect chains through the Processor contract.

Canonical: https://maru.audio/docs/dsp-midi-and-composition
Documentation index: https://maru.audio/llms.txt

The same Processor architecture supports MIDI utilities, timed playback and
multi-effect products. A note mapper or sequencer is a reusable module with
ports, state and parameters; its host connects it into a chain.

## Inputs, outputs and clock ownership

Declare audio and MIDI ports in the Audio SDK. The host delivers events and
prepared resources; the Processor advances time and emits events through the
shared contract. `processor` supplies `ProcessorDefinition`, `ProcessSpec` and
`ProcessorBlock`; `processor-events` supplies the event vocabulary. An event-only
Processor can declare zero audio inputs and outputs while still processing blocks.
See [Define a Processor module](https://maru.audio/docs/processor-module.md).

Use `control/musical-clock` for musical units and frame boundaries, rather than
rounding each note interval independently. Preserve note-off and panic behavior
on stop, loop, transpose or resource replacement. `mpe-ingress` translates
member/master expression with note identity; the destination must support those
events to preserve independent expression on overlapping notes of the same pitch.

## Effect ordering and live transitions

`processors/serial-effect-stack` schedules one to six slots with stable
identities and bounded transitions. The consuming Processor owns each effect’s
prepared state and controls. The scheduler fades to dry, commits a topology
change, waits for the revision-matched clear acknowledgement, then fades back.
Its global staged-clear budget is 256 scalar stores per input frame.

`processors/multi-effect-chain` supplies the reusable MultiFX composition;
its focused subpaths expose the same chain’s controls, mappings and effect
groups. They are pieces of that composition, rather than alternate leaf
algorithms. Use the leaf categories when building a smaller custom effect.

## Playback and reference processors

`clip-player` plays prepared stereo clips with source-rate conversion and
transport. `stem-player` keeps four prepared stereo stems aligned. Neither is
a file downloader or decoder. MIDI timeline/pattern readers similarly consume
prepared event data. Resource installation and device access stay with the host.

The `reference-smoothed-gain` and `serial-effect-stack-reference` entries are
qualification examples, useful for understanding deterministic execution and
scheduling. They are not complete musician-facing products. The root `dsp` and
`processors` barrels provide discovery; import focused processing paths in a module.

## Toolkit reference

Import paths below are suffixes of `maruaudio/dsp/`. Use the exported types
and setters in your installed version for complete signatures and defaults.

### Processors

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `processors/midi-timeline` | Bounded sample-clock MIDI timeline playback shared by prepared MIDI sources, including note release and loop transport. | `createState`, `process` |
| `processors/midi-note-map` | Prepared four-voice MIDI note maps with held-source snapshots and shared-output reference counting. | `createState`, `process` |
| `processors/reference-smoothed-gain` | Qualification-only mono f32 smoothed-gain processor with deterministic reset. | `createReferenceSmoothedGainState`, `processReferenceSmoothedGain` |
| `processors/serial-effect-stack` | Bounded serial effect scheduling with stable slot identities, opaque type tags and queued live transitions. | `createSerialEffectStackState`, `serialEffectStackProcessesWet` |
| `processors/serial-effect-stack-reference` | Qualification-only restricted three-stage consumer of the serial effect scheduler. | `createSerialEffectStackReferenceState`, `serialEffectStackReferenceTick` |
| `processors/mpe-ingress` | MIDI 1.0 MPE zone/member expression translated into identified notes and note-expression events. | `createMpeIngressState`, `processMpeIngress` |
| `processors/multi-effect-chain` | Prepared reusable MultiFX chain engine. | Re-exports the focused helpers below. |
| `processors/multi-effect-chain/constants` | Stable constants and algorithm vocabulary for the MultiFX chain. | `MULTI_EFFECT_CHAIN_PROCESSOR_SLOT_COUNT`, `MULTI_EFFECT_CHAIN_PROCESSOR_ORDER_COUNT` |
| `processors/multi-effect-chain/controls` | Parameter updates and control application for the MultiFX chain. | `MULTI_EFFECT_CHAIN_BITCRUSHER_BITS_MIN`, `MULTI_EFFECT_CHAIN_BITCRUSHER_BITS_MAX` |
| `processors/multi-effect-chain/control-mapping` | Numeric control/macro mapping for the MultiFX chain. | `exponentialControl` |
| `processors/multi-effect-chain/drive` | Drive/distortion stages used by the MultiFX chain. | `createDriveState`, `driveTick` |
| `processors/multi-effect-chain/dynamics` | Dynamics stages used by the MultiFX chain. | `createDynamicsState`, `dynamicsTick` |
| `processors/multi-effect-chain/equalizer` | EQ stages used by the MultiFX chain. | `createEqualizerState`, `equalizerTick` |
| `processors/multi-effect-chain/filters` | Filter stages used by the MultiFX chain. | `createFilterState`, `filterTick` |
| `processors/multi-effect-chain/modulation` | Modulation stages used by the MultiFX chain. | `createPhaserControlsState`, `advanceStereoPhaserControls` |
| `processors/multi-effect-chain/reverbs` | Reverb stages used by the MultiFX chain. | `createReverbWidthState`, `processReverbTailEq` |
| `processors/multi-effect-chain/slots` | Slot state and dispatch for the MultiFX chain. | `createSlotPlaceholders`, `processSlotState` |
| `processors/multi-effect-chain/stereo-spectral` | Stereo and spectral stages used by the MultiFX chain. | `createStereoFrequencyShift`, `tickStereoFrequencyShift` |
| `processors/strum-notes` | Select a contiguous ascending chord-tone window for strummed note positions; caller-provided output length sets the position count. | `selectChordStrumNotes` |
| `processors/stem-player` | Aligned four-stem prepared stereo clip playback and mixing. | `createState`, `process` |
| `processors/clip-player` | One prepared planar stereo clip at any 8-384 kHz source rate: sample-clock transport with run/loop/normalised seek, 4-point Hermite resampling to the host rate and a 5 ms declicked master gain. | `createState`, `process` |
| `processors/division-clock` | Firmware-derived divided musical clock with free-running or external MIDI-clock timing and 48-frame quantization. | `createDivisionClock`, `divisionClockFreeMultiplier` |
| `processors/pattern-arpeggiator` | Firmware-derived two-engine arpeggiator with held/latched notes, orders, rests, random octaves and sustain gestures. | `createPatternArp`, `resetPatternArp` |
| `processors/midi-pattern` | Bounded held-note step patterns with fractional-frame timing, seeded selection, velocity and MIDI event input/output. | `createMidiPatternState`, `configureMidiPatternProcessor` |

### Control and clocks

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `control/param-macros` | Prepared macro-to-parameter table with linear, exponential, logarithmic and S-curve mapping. The owning Processor dispatches targets. | `paramMacroCurve`, `paramMacroValue` |
| `control/musical-clock` | Beat/time/pulse-to-frame conversion and tempo/transport anchoring; fractional grid boundaries avoid accumulated rounding drift. | `createMusicalClock`, `musicalSecondsPerBeat` |

Return to [DSP fundamentals](https://maru.audio/docs/dsp-fundamentals.md) for I/O, lifecycle,
units and the category map.