Skip to content

Latest commit

 

History

History
1551 lines (1337 loc) · 91.9 KB

api.md

File metadata and controls

1551 lines (1337 loc) · 91.9 KB

Engine API

A machine is a folder under machines/ named after the machine. Every kind has machine.json and definition.json; the C++ it supplies depends on its kind:

Kind C++ the machine supplies Example
synth engine.cpp with Voice/Shared state, display.cpp and panel.svg.fragment; control.cpp with track control (SDK 1.9) 2op FM, Macro Osc
drum The synth callbacks and drawing display, plus per-key model/control callbacks (synthesis drum kits), from SDK 1.8 Independent model selection on 24 keys
sample sample.cpp with Voice state; the stock sampler it forks provides its screen, or from SDK 1.8, forking the sampler, optionally its own (display.cpp and panel.svg.fragment) Timestretch
effect fx.cpp with State; the stock FX page is its screen, or its own (SDK 1.7) Ring Mod

The first-machine walkthrough creates a standalone synth and previews it without native integration. SDK adapters own allocation, C linkage and stock registration.

Platform rules

These come from the stock firmware, not from SDK convention. Breaking one fails the build or, for the artwork rule, halts the device's SVG parser.

Area Rule
Machine folder C++ source, metadata, artwork, engine-specific generators and sound tests; Blackfin assembly only as native routines in native/
C++ Freestanding C++11: no exceptions, RTTI, static constructors, allocation, OS headers, #if, inline assembly or platform macros
Callbacks Bounded work per 64-sample block; no blocking, logging, file access or graphics from audio callbacks
Synth controls Four control positions, plus up to four alternates and a Shift row of up to eight (SDK 1.13); values arrive as Q31 and the stock menu stores Q15 defaults
Audio 64 frames at 44.1 kHz, Q31 output peaking at most at half scale; mono by default, optional stereo for synths (SDK 1.12) and sample engines
Identity The name follows the identity rules and never changes once published; a firmware's layout gives the numbers
Sample engines The sample is read-only and borrowed for the voice's lifetime
Effects State fits in 476 bytes and holds no resources (no destructor ever runs)
Artwork At most four decimal places and no exponent notation in any number; explicit paint on every leaf; no style, events or external references

The firmware contract explains where each rule comes from.

Memory and limits

Every selected machine and the SDK share one 2032 KiB module region: code, constant data and zero-initialized state together. It is the 2 MiB the firmware reserves from its heap, minus 16 KiB of relocated stock tables (4080 KiB with the builder's experimental 4 MiB option). There is no per-machine allowance: a build that does not fit names each machine's share, and sdk.py compile and the builder's memory meter report the same figures for standard memory. State usually dominates, since a synth's voice pool is voiceBytes × (min(voiceCapacity, 27) + 1): stock never sounds more than 27 notes, and one spare voice serves a note that ended as another starts. The SDK adds 12 bytes per stock voice index (3 KiB) and 16 per voice.

The limit applies to what someone installs, not to the whole catalog. When a collection doesn't fit at once, sdk.py compile links Open-XY's own machines and requires each other machine to fit beside them, as the builder offers it.

Limit Value Why
Module memory 2032 KiB for the selected machines Firmware heap reservation minus the relocated tables
Voices 1..256 per machine Stock voice indices
Effect state 476 bytes The 480-byte stock FX slot minus its object header
Synth controls 4 positions, at most 8 parameters, and a Shift row of at most 8 (SDK 1.13) The stock four-knob page and eight-word parameter vector; the row takes two spare track words
Sample and effect controls 1..8 The stock eight-word parameter vector
Control labels 8 characters The stock parameter page
Display shape ≤ 4 paths of ≤ 64 points, ≤ 512 nodes (more than 256 need "sdk": "1.8"), ≤ 16 text slots (more than 4 need "sdk": "1.3"), ≤ 16 palette entries Fixed-size renderer object and frame

voiceBytes, sharedBytes and display state have no limit of their own beyond whole words and module memory. Browser previews run 8 voices in 2 MiB of fixed WebAssembly memory, with growth disabled. This browser allowance does not change the native collection's module limit or measure its footprint. A drum preview auditions one parameter set across its voices; the device provides per-key drum settings.

CPU

The OP-XY renders every voice and effect in 64-sample blocks, 1.45 ms each, on one Blackfin core that also runs its own engines, sequencer and effects. A machine's cost adds up per sounding voice and per track that uses it. The SDK reports a host estimate during development; catalog submissions require the separate hardware measurement of average and peak CPU.

python sdk.py test prints an estimate for synths and effects in Blackfin instructions per 64-sample block, at the machine's heaviest control setting. It times the machine's render (or process) on your computer against a reference loop in the same run, a table oscillator through a one-pole filter of known Blackfin instruction count (about 590 per block), so the figure is about the same on any computer:

CPU estimate (host-timed; not measured on the device): Karplus about 7,700 Blackfin instructions per voice block at its heaviest setting. Aim for at most 15,000; for scale, 2op FM about 14,000, Macro Osc (Braids) about 9,000
Per 64-sample block Aim for at most Likely to drop audio above Core machines
A synth voice 15,000 24,000 2op FM about 14,000, Macro Osc (Braids) about 9,000
An effect, once per track 30,000 48,000 Ring Mod about 10,500

Above the aim, make the machine lighter where you can; above the second limit, measure it on a device with many notes held across tracks. Instructions are not cycles: pipeline stalls add some. And the estimate understates what the host does fast and the Blackfin does not:

  • Division has no hardware instruction and costs tens of cycles on the device. Divide once per block, or use a table or a reciprocal. For a 16-bit quotient by a divisor below 32768, such as a sub-sample edge position, divide.hpp's quotient16 is exact and inline: 17 single-cycle divide steps on the device.
  • Floating point has no hardware either. Keep audio in integers; q31.hpp has the fixed-point helpers: a saturating multiply, and (SDK 1.7) a saturating add, one instruction each on the device.
  • 64-bit arithmetic and floating point may need software helpers. The build links only the required authenticated arithmetic runtime members; their code counts toward module memory.
  • Per-sample work that changes only per block, such as coefficients and increments, belongs outside the sample loop.
  • Loops inside a large render often aren't compiled as hardware loops: GCC then tests and branches on every sample. Give each hot sample loop a small function of its own (__attribute__((noinline))), with the state it needs copied into locals and written back after.
  • Rare branches in a sample loop, such as a wrap or a discontinuity, can cost several cycles on every sample if GCC makes the common path the taken one. Mark them __builtin_expect(condition, 0) so the common path falls through, or make them branch-free.
  • 16 x 16 products that GCC widens into 32-bit multiplies cost more: q15.hpp's product is always the one 16-bit multiply.
  • Dispatch per sample through a chain of sections or modes (switch on an order, an on/off test) costs branches on every sample. Run each section over the whole block in turn instead.
  • A hot loop the compiler schedules poorly can become a machine's own hand-written native routine, once the C++ is as lean as it gets.

Measure and publish the required hardware CPU readout before submitting a catalog entry: add both average cost (block_percent) and worst observed block (peak_percent) from the generated report. A low average can hide a short spike; host estimates do not satisfy either measurement requirement.

Native routines

A machine can carry its own Blackfin assembly for a few hot loops. Each routine lives in native/<name>.s beside a C++ header holding its declaration and a portable C reference, and native/<name>.json describes it. A firmware build assembles the routine and links it into that machine alone, counted in its memory; host tests, CPU estimates and browser previews run the reference. Write the reference first: the C reference defines the behaviour. The routine must compute exactly what it does, sample for sample, for every input the manifest's range admits. Check that on a simulator or the device before publishing; the SDK checks only the routine's shape. Macro Osc's native/ in the core machines holds six routines and its tests of their references.

mymachine/
  native/gain.s      the device routine
  native/gain.json   its manifest
  native/gain.hpp    its declaration and C reference, included by the machine's C++

The header names both with OPXY_NATIVE from native.hpp, which picks the routine in a firmware build and the reference everywhere else, so machine C++ still needs no #if. The two must have the same type, which the macro checks:

#pragma once
#include <opxy/native.hpp>
#include <opxy/types.hpp>

extern "C" void mymachine_native_gain(opxy::i32* samples, unsigned count, opxy::i32 gain);

namespace mymachine {
// The definition: each sample's high half times gain (0..32767), doubled.
inline void gain_reference(opxy::i32* samples, unsigned count, opxy::i32 gain) {
    for (unsigned i = 0; i < count; ++i) samples[i] = (samples[i] >> 16) * gain * 2;
}
inline void apply_gain(opxy::i32* samples, unsigned count, opxy::i32 gain) {
    OPXY_NATIVE(mymachine_native_gain, gain_reference)(samples, count, gain);
}
}
/* mymachine_native_gain: native/gain.hpp's gain_reference on the device. */
.section .text
.align 4
.global _mymachine_native_gain
.type _mymachine_native_gain, STT_FUNC
_mymachine_native_gain:
    CC = R1 == 0;
    IF CC JUMP .Ldone;                /* a loop count of 0 would still run once */
    P0 = R0;
    P1 = R1;
    LSETUP (.Lstart, .Lend) LC0 = P1;
.Lstart:
    R0 = [P0];
    R0 = R0.H * R2.L (IS);
    R0 <<= 1;
.Lend:
    [P0++] = R0;
.Ldone:
    RTS;
.size _mymachine_native_gain, .-_mymachine_native_gain
{
  "symbol": "mymachine_native_gain",
  "stackBytes": 0,
  "range": "gain 0..32767, any count",
  "reference": "mymachine::gain_reference (native/gain.hpp)"
}
Manifest field Meaning
symbol The routine's C name, <id>_native_<name>: the machine's own prefix, so routines of different machines never collide. The unit exports this one symbol
stackBytes The most stack the routine takes below its caller's SP, pushed registers and LINK frame included, the functions it calls aside; a multiple of 4, at most 2048. The build's audio stack bound counts it, and the build fails if the routine's measured frame is larger
range The inputs the routine supports, for its readers. The header sends calls outside it to the reference
reference Optional: the C reference that defines it
stateBytes Optional: writable .data and .bss bytes the routine keeps between calls, such as a cache; 0 (none) by default

A routine follows the compiler's calling convention, which the C++ calling it relies on:

  • Arguments arrive in R0, R1 and R2. The caller reserves 12 bytes for them at the top of its frame, so a fourth argument is at [SP + 12] on entry and a fifth at [SP + 16]. A result returns in R0.
  • R4 to R7 and P3 to P5 are preserved: push the ones the routine uses ([--SP] = (R7:4, P5:3);) and pop them before RTS. FP and SP are preserved too, and RETS when the routine calls anything. R0 to R3, P0 to P2, I0 to I3, M0 to M3, B0 to B3, A0, A1 and ASTAT are free to use.
  • L0 to L3 are zero on entry and must be zero on return: compiled code addresses through I0 to I3 assuming no circular buffer. A routine that sets an L register for a circular buffer clears it again before it returns.
  • Hardware loops (LC0/LT0/LB0 and LC1/LT1/LB1) are free to use: compiled code never keeps a loop running across a call. Leave each loop through its bottom, or clear its LC before jumping out early, so no loop stays armed. The usual Blackfin rules apply: a loop count of 0 still runs the body once, and a loop body does not end in a jump, call or return.
  • The stack moves only by push, pop, LINK/UNLINK and SP += constant, the forms the build's stack analysis measures.

Before compiling, sdk.py test and the firmware build refuse:

  • assembly anywhere but native/<name>.s (vendored code, never built, aside), a unit without its manifest, or a manifest without its unit;
  • sections other than .text and .rodata (and .data and .bss with stateBytes), section flags, directives that pull in or generate text (.include, .incbin, .irp, macros with arguments; a macro without arguments only repeats statements the checks see) or change linkage (.weak, .comm), and exports other than the manifest's symbol;
  • supervisor and system instructions (RAISE, EXCPT, IDLE, CLI, STI, returns other than RTS, TESTSET, cache flushes), the system registers (SYSCFG, SEQSTAT, RETI and the other return registers, USP), writes to the cycle counters, which profiling owns, and a memory-mapped register's address set as a constant high half of a pointer or index register;
  • an indirect CALL, whose callee the stack analysis cannot follow (an indirect JUMP stays inside the routine), any other way of moving SP, and an L register set and never cleared.

The firmware build checks the assembled object again: its sections, and one global function in .text, the manifest's symbol. These are cheap checks of a routine's shape, not proof of what it computes: that is the reference's, and the machine's tests'.

Definition

Every machine kind keeps its controls in definition.json (for example 2op FM's); the validator rejects missing or unknown fields.

Field Contract
schema 1
id The machine's name; also its C++ namespace
name Display name
parameters Ordered controls, each with id, label, default, mapping, display: four to eight for a synth (see alternate controls), exactly eight for a drum kit, one to eight for a sample engine or effect; an effect's after the fourth are alternates on its send page. Labels are at most eight letters, digits or spaces
shift Optional: an effect's shift row (SDK 1.7) or a synth's Shift row (SDK 1.13)
presets Named maps containing exactly the declared controls (a Shift row's aside); may be empty
resources What the kind declares about its storage (below)

Controls are finite numbers in [0, 1]. Mappings support linear (minimum + (maximum - minimum) * value), three or more increasing anchors interpolated evenly, power (maximum * value^exponent, exponent other than 1), exponential (minimum * (maximum/minimum)^value) and enum. Display formats are ratio, percent (the normalized value scaled to 0.0–100.0, without a suffix), bipolar (a -1..1 value as a signed percentage), duration, semitones, enum and division (SDK 1.2: one of stock delay's eight note lengths, below). Mappings describe the control for previews and the builder; the C++ applies its own mapping. Enum quantization matches the native Q31-to-Q15 path. On the device, a synth's or send effect's enum of up to 255 choices moves one choice per encoder detent (two when turned fast), in plain and locked edits alike, and stores the middle of the choice's range; a larger enum keeps stock's 0..99 stepping. Its value text on the engine or send page is the selected choice's label. Parameter order and mapping changes affect saved sounds; the UX conventions cover direction, defaults and adding parameters. The stock parameter page shows labels in lower case.

Alternate controls

A synth's first four parameters belong to the four encoder positions of its page. Up to four more are alternates: each also names its position with "control": 0..3. Pressing that encoder cycles the position through its own parameter, then its alternates in parameter order; turning it edits the one shown, whose title and stock percentage the page shows. Every parameter keeps its own slot in the eight-word vector, so render receives all of them and presets, projects and the catalog's defaults store each one. The selection is per track, starts on the position's own parameter and is not saved. The track menu's scramble randomizes alternates along with the first four; an empty placeholder among the alternates keeps its value. Display inputs carry each position's shown value, its parameter index (shown) and every parameter's value (slots), so a header value can format whichever is shown while dials follow their own parameters. Browser previews show the parameter last edited at each position.

A send effect's parameters after the first four are alternates on its send page in the same way. Each may name its position with "control": 0..3; without one, parameter i alternates on position i - 4. A press cycles the position, its turns edit the parameter shown, and the page shows that parameter's title and value. When an effect is put on a send, the SDK stores its fifth to eighth defaults as stock stores its first four, so process receives them before they are first edited. "press": "page" is for synths only. A send effect's LFOs keep stock's four destinations, its first four parameters.

A synth with five to eight parameters may declare "press": "page" at the top of definition.json: pressing any encoder switches the whole page. Each position may have at most one alternate. Positions without an alternate show and edit their original parameter on both pages, with one saved value, not a duplicate parameter. Eight-parameter pages require SDK 1.3; partial second pages require SDK 1.4. The four shown entries identify the selection: look for any alternate, since the first column may be shared.

Browser previews select a page when editing one of its distinct parameters; editing a shared control keeps the current page. Use the SDK's two-page header for fixed rows, active-row emphasis and motion. sdk.py new supplies it by default. Macro Osc is the worked reference.

A synth or drum kit for which a stock instrument page means nothing (one that makes no sound of its own, say) may declare "hidePages" at the top of definition.json (SDK 1.9), listing "envelope" (M2), "filter" (M3) or both. A drum kit's M3 is its track filter, shown unless hidden. On its track, those keys then leave the page shown as it was, and selecting the track while another track shows a hidden page shows the engine page. The SDK corrects the page once per GUI tick, so the hidden page may flash for a frame. The LFO page (M4) always stays on instrument tracks. Aux replacements own their pages and receive their page keys directly; see aux tracks.

A synth may leave a slot empty yet keep later parameters at their indices (projects save by index): declare it {"id": ..., "label": "", "default": 0, "mapping": {"kind": "linear", "minimum": 0, "maximum": 1}, "display": "percent", "absent": true}, with no preset entry. It belongs to no position, so no press selects it; an empty own slot still starts its position's cycle, so the press reaches the position's alternates. Its title is empty and a turn on it changes nothing; a machine's display can blank its value with header text " ". A paged synth may give an absent slot after the first four a control: that position's second page is then the empty slot, blank and inert, rather than its first-page parameter again.

On instrument tracks, the Value, Random and Element LFOs can target every declared parameter of a custom synth or sample engine, including all eight when present. Destination names follow parameter order regardless of which alternate the engine page shows. Synth destination icons follow each parameter's assigned encoder, including alternates that share an encoder. Sample-engine icons repeat for the second row of four controls. Turning stops at the first and last declared destination; pressing cycles through the declared destinations and wraps to the first. Extended machines use eight selector positions, bounded to their declared count. A retained destination beyond the machine's count resolves to its last parameter in audio, labels and icons. Stock engines and machines with at most four parameters retain stock selection. When opening projects saved with older firmware, reselect LFO engine destinations on machines with more than four parameters: their saved selector values now address eight slots instead of four.

On custom synth engine pages, Shift + turn edits the same visible parameter at one tenth of the normal rate, unless the synth has a Shift row. Enum choices keep their one-choice stepping. Synth amounts and bounded positive anchor-ratio captions show one decimal place; amounts omit the percent suffix. A machine's display can replace them with its own header text. Custom send effects also use the slower Shift rate for continuous controls, with stock FX captions except for enum and division controls.

A sample engine declares voiceCapacity, which must be 256 (stock creates a voice for each of its 256 voice indices and binds each to its sample), and the optional sample services it uses. An effect declares no resources ({}). A synth declares:

Field Required value or meaning
voiceBytes, voiceAlignment Voice size (whole words) and alignment, checked against the compiled type
voiceCapacity Notes that sound at once, 1..256. Stock plays at most 8 notes per track and fades a note it takes, so 8 keeps a machine on one track within its own voices; allow 8 for each track it plays on at once. Values above 27, stock's voice slots, keep 27 voices plus the spare (28). Stock's 256 voice indices share these voices and one spare (synth voices)
sharedBytes Shared size, or 0 when Shared is empty
outputPeakQ31 Positive declared oscillator peak; the preview uses it for audition gain
stereoOutput Optional integer 0/1 (SDK 1.12): write 64 interleaved left/right frames, 128 words
releaseCallback Optional integer 0/1 (SDK 1.12): receive the voice release event
display The screen's frame budget; see the display API
trackControl Optional: the track control state's stateBytes and stateAlignment, and optionally unique, savedBytes, aux and sharedLfo

The SDK never runs constructors or destructors for Voice, Shared or DisplayState: their storage starts zeroed and the callbacks set it up. Exceptions and allocation are not supported.

A synth's Shift row

A synth may declare a Shift row (SDK 1.13): up to eight more controls, which Shift and an encoder turn on its engine page, as Shift reaches the second row of a drum kit's or an effect's controls. With two pages ("press": "page"), that makes sixteen controls: two pages of four, and a Shift row under each. List them in "shift" in definition.json, declared as parameters are; entry i sits under page i / 4, encoder i % 4, so a synth of four controls may have four entries and a paged synth eight. An entry may be absent to keep the later ones under their encoders:

"press": "page",
"shift": [
  {"id": "noise", "label": "Noise", "default": 0, "display": "percent",
   "mapping": {"kind": "linear", "minimum": 0, "maximum": 1}},
  {"id": "octave", "label": "Octave", "default": 0.5, "display": "enum",
   "mapping": {"kind": "enum", "labels": ["-2", "-1", "0", "+1", "+2"]}}
]

render then receives sixteen words: the eight controls, then each entry's word, in the same Q31 form as the controls, 0 beyond the row:

const opxy::i32 noise = parameters[8];
const opxy::u32 octave = ((static_cast<opxy::u32>(parameters[9]) >> 16) * 5) >> 15;
  • Steps. A continuous entry moves in whole steps from 0 to 100, one a detent and up to four when turned fast, and plays step / 100 of full scale; an enum (at most 128 choices) moves one choice a detent and plays the middle of the choice's range, read as any enum control. Without a Shift row, Shift turns a synth's own controls in fine steps; with one, it turns the row.
  • Where it is kept. In two words of the instrument track that no stock page, preset key or engine uses, which stock saves and loads with every pattern of the project (firmware). A project saved before the machine had its row, a new project and a track newly given the machine play the row's defaults.
  • Presets keep it, as a drum kit's presets keep its keys: a preset saved on the OP-XY carries the row in its regions (Drumline's, with no sample), and loading it plays the row it was saved with. A preset without them, saved before SDK 1.13 or written without the row, plays the row's defaults. A preset in definition.json may set any of the row's controls; the rest keep their defaults. A preset file written by other tools carries the row as one region, {"model": "fm slap", "params": [...]}, its four params from tooling.definitions.shift_preset_params; one saved on the device is the surest form (firmware).
  • Locks per step, as a drum kit's Shift fields lock: hold a step, hold Shift and turn; the step plays that entry at the value turned to, and turning it back to the track's value unlocks it. A lock acts from the step's note start on every voice the track is sounding, as a stock lock does, and copies, pastes and saves with its step. Recording a Shift turn without a step held changes the row, and records nothing. With slide on, the row's locks don't slide. Locks on the page's eight controls, and the LFOs that reach them, are stock's, unchanged; the LFOs don't reach the row, and the track menu's scramble leaves it alone.
  • What it costs. Presets and locks use the drum kits' preset hooks and step-lock service, so a build with a Shift-row synth links them: about 86 KiB of module memory, most of it the lock pool, once for the whole build.
  • Showing it. While Shift is held, the stock header names and captions the entries under the page the encoders are on. A machine drawing its own header reads the row from opxy/synth_shift.hpp, and the two-page header shows it in the bright row. Holding Shift and pressing an encoder does not switch pages: let go of Shift, press, then hold Shift again.
  • Where it runs. Instrument tracks 1–8; a synth with track control can't have one. Browser previews show each entry as a control of its own: editing one shows the row, and their audition plays it.

Audio buffers and ownership

opxy/audio.hpp defines the callback types.

Argument Contract
Voice state SDK-owned, correctly aligned storage; the engine initializes all sound fields
Output Writable signed Q1.31 buffer: 64 mono words, or 128 interleaved words with stereoOutput: 1; write every sample
Parameters Read-only normalized Q31 words, eight; the declared controls in order, then zero. Sixteen for a synth with a Shift row: then the row's eight
Pitch Read-only 64-word unsigned phase-increment buffer, modulo 2^32 cycles

Pointers are non-null, aligned and non-overlapping. Do not retain borrowed buffer pointers beyond the call. round(normalized * 2147483647) produces a control word. Physical units are the engine's mapping, not the buffer format. Use Q31 helpers for defined multiply/rounding; phase arithmetic wraps instead of saturating like audio.

Callbacks perform bounded work without allocation, blocking, file access, logging or graphics. Device amplitude envelopes, filters and mixing follow the oscillator callback; the browser supplies a simpler audition gate and mixer.

Lifecycle

Every synth implements four callbacks in its declared namespace:

struct Voice { ... };   // one voice's state
struct Shared { ... };  // state shared by every voice; empty when nothing is shared

void initialize(Voice& voice, Shared& shared, opxy::u32 owner);
void start(Voice& voice, Shared& shared, opxy::u32 owner);
void destroy(Voice& voice, Shared& shared, opxy::u32 owner);
void render(Voice& voice, Shared& shared, opxy::u32 owner,
            opxy::Output output, opxy::Parameters parameters, opxy::Pitch pitch);

Storage begins zeroed; owner is a stable nonzero voice ID, the stock voice index plus one. Each of the machine's voiceCapacity voices serves one owner at a time: initialize runs when a voice goes to an owner and establishes all sound state; start runs on each note; destroy releases anything the voice holds in Shared, once stock has stopped rendering its note (it ended, or stock took it and restarted the index) or another note has taken the voice. The adapter notices an ended note within about three blocks while the machine renders other notes; after the machine's last note it notices at the next note start. A taken note renders one last block fading to silence, then renders silence; no voice index ever fails, whatever the capacity. Callbacks run serially per voice. The browser preview's voice stealing and panic use the same callbacks, but the preview always keeps 8 voices and takes the oldest at once: it does not model voiceCapacity, stock's renders, the spare or the fade. The SDK adapter owns the firmware object header, method table and voice pool; none of that belongs in Voice.

LeasePool provides fixed typed resources. acquire reuses an owned slot or clears the free/oldest slot; get verifies ownership; release cannot free a stolen lease. The engine decides how a voice behaves after losing a resource. This pool has no locks and requires serialized access.

Track control

A synth can steer other tracks (SDK 1.9). A build without such a machine (or one with hidden pages) applies none of track control's firmware edits and links none of its code. Such a synth runs on an aux track, never in an instrument track's place. It declares "trackControl": {"stateBytes": n, "stateAlignment": a, "unique": true, "aux": [12]} in resources, with "sdk": "1.9" in machine.json, and supplies control.cpp with:

struct ControlState { ... };  // trivial, standard-layout; starts zeroed
void control_reset(ControlState& state);
void control(ControlState& state, const opxy::control::Input& input, opxy::control::Overlay& overlay);

track_control.hpp defines the types. control runs on the GUI side once per stock GUI tick while its machine holds an aux track (aux tracks). Currently only track 12 is supported, so one controller runs in each pattern. unique: true is required: it has one ControlState. opxy::control::copies(track) reports the number of tracks holding that machine (browser previews answer 1). control_reset runs before its first call and whenever it arrives on a track.

Input field Contract
track The aux track the machine holds, zero-based
values[track][index] Every track's 58 live parameter words (all_tracks, 16; aux tracks are 8..15), as stock sets them (edits, parameter locks, sequencing), without any machine's overlay. Indices 0..7 are the engine's controls; the rest are stock's own track parameters, in stock's units. The machine's own engine controls are the values its page shows, including its LFO
elapsed_us Microseconds since the previous tick, from the core clock: 0 on the first tick after a reset, at most one second
transport The project's tempo in tenths of BPM (0 when unknown), the song position in 96ths of a quarter note, which advances only while playing, and whether the sequencer plays
page_key Last directly handled page key since the last tick: 1..4 for M1..M4, or 0. M1 returns to the machine page; M2/M3 leave the current page alone. With sharedLfo: true, M4 belongs to the shared LFO and is not delivered
muted 1 while the machine's track is muted in the current scene (aux + track key, or the mixer). As with stock's brain, a muted machine has no effect: none of its overlays apply. It still runs, so its page can say so
shift 1 while Shift is held
turn_count, turns While the copy takes its own turns (below): up to 16 turns of its track's encoders since the last tick, oldest first, each the parameter slot its position shows (0..7, after presses) and a direction: the detents it covers, signed, ±1 for a slow detent and up to ±8 when turned fast (SDK 1.11)

overlay arrives empty; opxy::control::add appends up to 64 entries, each a track, parameter index and value for this tick. Entries for the machine's own track or outside the table are ignored, the last entry for a parameter wins and negative values count as 0. When two machines overlay one parameter, the one on the later track wins. A parameter no machine overlays any more returns to stock's value. Overlays are live values only: saved projects keep stock's values, and an edit or parameter lock under an overlay reaches values on the next tick. Pages show an overlaid parameter's overlay, whether or not the sequencer plays; for a moment after the parameter's encoder is turned, they show the track's own value, which the turn changes.

A step's parameter lock plays as written: while a lock holds a parameter, no overlay is written over it. The lock ends when stock sets the parameter to something else, a step (24 ticks) after it was written if the track then plays its own value, or when the sequencer stops; the next tick overlays it again. Loading or creating a project discards outstanding overlays. Like the display, control is bounded and allocation-free; it is not an audio callback. Browser previews do not run it.

A machine can play notes on instrument tracks (SDK 1.11): opxy::control::play(overlay, track, pitch, velocity, length_us) appends up to 32 a tick, for tracks 0..7, pitches 0..127, velocities 1..127 and lengths above 0; others are dropped. The SDK starts each at once through stock's live note-on, as the track's keyboard would play it, so the track's own machine sounds it, but stock never records it. The SDK ends each note after its length (at most eight seconds), when the sequencer stops, when a project loads, or when the copy leaves its track, and a note on a track and pitch the copy already holds ends that one first. At most 32 notes from every machine sound at once, and none starts while stock's table of sounding notes (50, shared with the keyboard and the sequencer) holds 32 or more, so the keyboard and sequencer always keep 18; notes over either limit are dropped. Stock tells the SDK's notes from the keyboard's only by track and pitch: a key held on the same track and pitch can end the machine's note, or the machine's note-off can end the key's. A muted machine plays no notes, and its sounding notes end. Notes start on GUI ticks, so a machine that follows transport plays each when the first tick after its time arrives.

Setting overlay.own_turns to 1 (SDK 1.11) asks for the machine's own encoders for the next tick: while it does, a turn of its track's encoders on its page edits nothing and arrives in turns instead, so the machine can give its pages controls of its own (with hidePages, the pages it hides can be its own). Presses still switch alternates, and Shift does not change the slot. Turns wait for the next tick for one track only: turning a second track's encoders first drops the first track's. A project load hands the encoders back to stock until the machine asks again.

A unique machine can keep data with each project, such as Morphose's states. It adds "savedBytes": n (1..8192) to trackControl and supplies:

u32 control_save(const ControlState& state, u8* data, u32 capacity);  // bytes written, at most capacity (n)
void control_load(ControlState& state, const u8* data, u32 bytes);

When stock saves a project, the workspace included, control_save writes what to keep; the SDK stores it in the project's companion. After stock loads a project, control_load gets those bytes back, or bytes 0 when the project has none (saved before, on stock, or without the machine) or is a new one, so the machine can start empty. Both run on the GUI side. Such a machine's control_reset runs just before each control_load, and when it arrives on a track only if no load has run since startup: its state is the project's, through every pattern change.

A machine's control and display are compiled separately, so they share no variables. The control can pass sixteen words (four before SDK 1.11) to its display each tick in overlay.display, which the display reads with opxy::control::from_control(index): the words of the copy on the selected track, 0 when it did not run, and always 0 in browser previews.

A machine draws only on its own page: track control paints nothing over other tracks' pages.

Reading and setting other tracks

A track control machine reaches instrument tracks 1-8 (indices 0..7) three ways:

To Use Lasts
Get a value input.values[track][index]: the live word, as stock sets it, without any overlay Read each tick
Set it live opxy::control::add(overlay, track, index, value) This tick only: stock's value comes back when the machine stops adding it, and the project never saves it
Set it stored opxy::control::store(overlay, track, index, value) Until something else sets it: the track's current pattern keeps it, the project saves it and the page shows it, as an encoder edit would

store returns false, and writes nothing, for a track outside 0..7, an index outside 0..57 or once this tick holds store_capacity (16) stored writes. The SDK applies them in order after control returns: it sets the stored value, then calls stock's setter that an encoder edit ends in, which publishes it, so values holds it from the next tick. It ignores a write to the machine's own track, and every write while the machine's track is muted; negative values count as 0. Beneath an overlay of the same parameter, the overlay still plays, and its release restores the stored value. A step's parameter lock on it plays on as written; stock's next step plays the stored value. Use store for changes the user should keep (recalling a state), and overlays for movement (a morph or modulation): each stored write changes the project, as an edit does.

Indices 0..7 are the engine's eight controls, the rest stock's own track parameters. The SDK does not tell a machine a parameter's label, range or type: the engine's controls are 0..32767 for whatever the engine on that track names them, and stock's own words are in stock's units.

Aux tracks

A track control machine, unique and with its own display, runs on an aux track (SDK 1.9): it lists it in "aux" ([12], CV) in trackControl. That track is the only one for now, the one whose stock role the SDK keeps silent. Such a machine is not in tracks 1-8's engine list: it is chosen on its aux track only.

  • Choosing: Shift + M1 on track 12 opens a list, "engine", with the track's stock role (cv) first, then each machine that may take it over. As tracks 1-8 hold an engine, each pattern holds its own choice: it applies to the current pattern, is copied with it and saved with the project, and chained patterns switch between CV and the machine. While a machine holds the playing pattern, CV and gate stay silent. A new project starts with cv.
  • Its interface: M1 shows the machine's display. Its encoders, clicks, fine turns and parameter locks use the machine's controls directly; CV's page dispatch does not run. M2/M3 are delivered as page_key actions and do not open stock pages. hidePages is unnecessary for an aux replacement.
  • Optional shared LFO: "sharedLfo": true in trackControl gives M4 to the shared LFO page, naming destinations after the machine's first four parameters. By default M4 is another machine action, no stock page is exposed, and stock LFO modulation is excluded from the machine's controls. The shared LFO uses the track's existing LFO settings.
  • Its controls: words 0..7 of track 12, so they are sequenced, locked and saved like any track parameter, and values[11] holds them. Taking a pattern over sets the machine's defaults; giving it back restores the role's values (a pattern copied from one the machine held takes another pattern's). A project opened with a build that lacks the machine gets the role's values back too. Opened on stock firmware, CV plays the machine's values.
  • Presets: Shift + track key on track 12 lists presets in two columns, as stock's preset browser does: folders, then the presets in them that can run on the track. Choosing one gives the track to its machine (or role) and sets its controls. The builders install a machine's definition presets as content/aux_presets/<id>/<name>.json (names lowercased, at most 15 characters), and content/aux_presets/cv/init.json so CV is listed too; users add their own as aux_presets/<folder>/<name>.json over MTP. Each is {"params": [eight values 0..32767], "platform": "OP-XY", "type": "<machine id or cv>", "version": 1}. Without params, a preset only gives the track to its machine or role, leaving the controls as they were, as CV's init does.

It runs on the GUI side like any track control machine; nothing changes on the audio side but the silenced CV output.

Synthesis drum kits

SDK 1.8 adds "kind": "drum": one registered instrument with independent model selection and sound controls on 24 keys. It supplies the synth lifecycle, a drawing display, and the same resources plus modelCount (2..64). Each key holds a model and eight 7-bit controls. A kit of more than 16 models stores them in a prefix code, which holds at most 15 models that use all eight controls (parameter_count 8); sdk.py test --machine counts them and fails a kit with more; on the device such a kit's keys play their defaults and turn nothing. The definition declares the eight controls: slots 0..3 on the four encoders and slots 4..7 their second row, one per encoder. As a synth's two pages ("press": "page"), any press switches the whole row between slots 0..3 and 4..7, and a slot the key's model leaves unnamed shows blank; a drum kit declares no press. As on stock Drumline, Shift and the first encoder choose the selected key's model, and Shift and the second encoder its choke group, NONE or 1..3; keys sharing a group cut each other off. While Shift is held the first encoder's cell shows MACHINE and the model, the second's CHOKE and the group, and the third and fourth are blank and turn nothing.

A kit may name groups of consecutive models in resources.modelGroups, such as [{"label": "TRX", "count": 13}, {"label": "EFM", "count": 8}]: 2..16 groups, each with a label of at most eight letters, digits, spaces or hyphens and at least one model, whose counts add up to modelCount. Shift's first encoder then chooses the group (KIT), keeping the model's place in it, so a kit's first model stays first; the second the model within the group (MACHINE); the third the choke group (CHOKE); and the fourth turns nothing. A kit with padMix (below) may name groups too, but its Shift row has no KIT: MACHINE scrolls every model through the groups, and a group only titles its models.

With "padMix": 1 in resources (SDK 1.10; 0 or 1, omitted means 0), Shift gives each key the settings of a mixer channel. On the encoders' first row it chooses the model (MACHINE: every model in turn; in a kit with groups the cell's title is the model's group, TRX over BD), the choke group (CHOKE), and the key's own pan (PAN) and level (LEVEL), as on stock Drumline: pan -100..100 with 0 centred, moving faster on a fast turn as stock's does, and level in whole dB, -30..0, one a detent, shown as -6dB. Pan and level are stock's own pad fields. Stock pans every voice of a kit already; the SDK applies the level, as a cut, so a voice stays within its declared outputPeakQ31. A boost stock saved (up to +20 dB) plays and shows as 0 dB and stays stored until the level itself is turned down. On the encoders' second row Shift edits the key's pad fields: the kit's own pad controls on the first two encoders, then its FX I and FX II sends. Every key of such a kit has the second row, a model with four or fewer controls too, whose encoders there are blank. Shift always edits the row the encoders are on; the display's line says which. A press of any encoder switches the row with Shift held too, so Shift and a press reach the second row without letting go.

Each key of a padMix kit has its own FX I and FX II sends, as a Machinedrum track has its own delay and reverb sends: a kick can stay dry while the snare is wet, even with the track's send knobs at 0. A send at 0 (TRK) follows the track's send exactly; 1..7 send the key's own amount, shown as 0, 17, 33, 50, 67, 83 or 100, whatever the track's send knob says: a key at N sends what the track's knob at N would, through the same curve stock gives that send's knob. An amount scales the voice after stock's pan, level and envelope, and the track's level and mute still apply to it. The track's own mix is unchanged, and so is the source dry reduction of a send effect with a Dry control. The kit's DSP never sees the sends (firmware).

A key plays its level, pad controls and sends once the kit has set it up: the kit's first edit of a key does that, with its level at 0 dB and every pad field at 0, so the key sounds as it did. Until then a key plays at 0 dB with every pad field neutral, whatever stock or an earlier SDK build left in its pad record, so projects saved before SDK 1.10, and keys a stock kit filled, play as before. Projects keep a key's settings, and copying a pad copies them. A preset keeps all of a key's settings too: loading one on a padMix kit sets up every key the preset stores (its regions marked fm slap), with the level, pad controls and sends the preset holds (a region's gain, and its random, the pad word's top half: pad controls from bit 0, FX I's code at bits 9..11 and FX II's at 12..14) (firmware). A region without random loads every pad field at 0; the OP-XY's own preset writer names it on every key the kit has set up, and a kit preset written by other tools should name it on every region, "random": 0 included.

A padMix kit may declare up to two small settings of each key's own in resources.padControls (SDK 1.10), such as a filter and a sample-rate reduction: a list of {"label": "FILTER", "bits": 5, "signed": true}, each with a label of at most eight letters, digits, spaces or hyphens, and 1..7 bits, or 2..8 when signed (two's complement, so the field runs -16..15 in five bits), together at most 9 bits. A value always fits the display's signed byte. They step one a detent. 0 is neutral in every field, and a key the kit has not set up reads 0. The pad fields are kept in a stock pad word that stock saves with the project and copies with a pad. Before every render the adapter passes the played key's pad controls to

void drum_pad(Voice&, Shared&, opxy::u32 owner, const opxy::i32* values);   // optional; one per declared field
bool pad_control_text(opxy::u32 field, opxy::i32 value, char* text);        // optional; at most 15 characters

in the machine namespace; pad_control_text captions a value for the stock header (without it, or when it returns false, the number shows). The display's pad holds the selected key's pad fields. A kit's own header captions them itself.

Every kit's track runs stock's own track filter on its voices, as a synth track does (SDK 1.10). M3 is the filter, with stock's types (svf, ladder, z lowpass, z hipass and the rest), cutoff, resonance, envelope amount and key tracking, and its second row the track's level terms and FX I and FX II. Each voice gets its own filter and its own filter envelope (M2 with Shift: attack, decay, sustain, release), from the moment it starts, after the engine and before the track's amplitude envelope and pan, so a key's own tone (a FILTER pad control, say) and the track's filter act in series. M3's controls lock per step through stock's editor, as on a synth, and act on every voice the track is sounding during the step. With M3 switched off, as a kit's init preset has it (stock's fx, active: false), the kit sounds exactly as without the filter and costs one test a voice; switched on it costs about 1,300 to 2,600 instructions a voice a block depending on the type (the ladder and svf most), and a kit's profiling workload runs the ladder on every voice so its catalog figure includes it (firmware). A resonant peak more than 6 dB above a kit's half-scale ceiling clips.

A padMix kit's steps lock its keys' PAN, LEVEL, pad controls, FX I and FX II per hit and per key, as stock's steps lock a track's parameters. Hold a step and Shift and turn one of them: the step gets a lock of that field for the key the Shift row shows (the key the encoders edit: one held or selected with Shift, else the selected key), one unit a detent (PAN faster when turned fast, as without a step held). PAN (-100..100), LEVEL (-30..30 dB) and a pad control (as far as its whole span, at most 127) lock an offset to the key's own value, clamped to the field (LEVEL stays a cut, -30..0); FX I and FX II lock the send itself, TRK or 0..100, starting from what the key sends. A field turned back to 0 is unlocked. Each note the step plays gets its own key's locks from the moment it starts: it keeps them for as long as it sounds, and voices still sounding from earlier hits keep theirs. Other keys on the same step play their own locks, or none: select each key to lock it. While a step is held, the Shift row (and the display's pan, level and pad) shows what that step plays for the selected key; released, the key's own values. MACHINE and CHOKE turn nothing while a step is held: the model and the choke group belong to the key. Without a held step Shift edits the key's own values as above. A note played live gets no step's locks, only the key's own values.

The locks behave as stock's: copying and pasting a step or a pattern, page duplication, nudge, clearing a step or its locks and the take's undo all carry them, and they are saved with the project. A step keeps a handle to them in a lock word of its own (37); the values live in an SDK pool kept in the project's companion, open-xy.locks (projects), behind a storage interface (drum_lock_store.hpp). A pasted copy is a copy: editing it leaves the original. Limits and what is not kept:

  • A project holds 2,457 locked steps with one field for one key (24 KiB of values; a step with four fields takes 16 bytes). Once the pool is full a turn locks nothing more; unlocking makes room again.
  • The values are saved in the companion, before track control's state, which gets the room the locks leave.
  • Saved on firmware without these locks (stock, or a build without a padMix kit), a project keeps its steps' handles but not their values, which play nothing from then on. Opened there and not saved, it keeps both.
  • Turning these fields while recording records nothing; lock them by hand.
  • With slide on, these locks don't slide: each hit plays its step's own.
  • Synths have no such locks.

The engine's eight controls lock as before (firmware).

In the machine namespace, declare these callbacks in core.h and implement them alongside the engine:

void drum_defaults(opxy::u32 key, opxy::u8* model, opxy::u8* controls); // a model and eight values
void drum_select(Voice&, Shared&, opxy::u32 owner, opxy::u32 model);     // before every render
const char* model_name(opxy::u32 model);
const char* parameter_name(opxy::u32 model, opxy::u32 slot);
opxy::u32 parameter_count(opxy::u32 model); // 0..8: slots 0 to count - 1 are used

Keys passed to drum_defaults are canonical keys 53..76. Controls are integers 0..127; the model must be below modelCount. In a kit of more than 16 models, a key on a model of seven or fewer controls stores its first seven, so changing a key's model keeps every control the new model stores and its eighth reads the key's default. Keys are read in their kit's current layout: a kit that grows past 16 models does not carry over the keys it saved before. Names are static strings; parameter labels fit eight characters. Return an empty label for unused slots. The screen shows the selected key's controls and labels with the track's offsets applied, so a held step shows the values its locks play; the display's Input::model is the selected key's model. A slot is available when it is below the count and named: an unnamed slot shows blank and ignores turns. Integer edits already have one-unit precision, including Shift turns.

The adapter stores the model and the eight controls losslessly in four existing per-key preset words (eight 7 bits, the model 4), and marks the pad with Drumline type 7 in its model byte, keeping its choke group unless one is chosen. Unmarked pads, including those stored by earlier 1.3 builds' eight-value layout, use drum_defaults. The track's eight parameters are offsets to the eight controls, neutral at Q15 16384, so step locks edit controls; the model is not lockable. The adapter decodes the key's values, adds the offsets and clamps, calls drum_select with the model, then render with each control as raw << 24, 127 mapped to 0x7fffffff. Packed words never reach machine DSP. Presets and projects retain per-key settings using stock region storage.

With "chokeSameKey": 1 in resources (0 or 1; omitted means 0), a kit plays one voice per pad and track, as a Machinedrum track does: a note cuts the kit's other voices still sounding the same track's same key, at any octave (the same pad). Each cut voice keeps rendering while it fades out linearly over 128 frames (2.9 ms), then is destroyed and its note retired; its own handle retriggered keeps its voice and does not fade. When a note needs a voice and none is free, a voice already fading goes before the oldest note's. Without the flag, notes on one key layer, up to voiceCapacity. This is separate from the choke groups Shift chooses, which stock applies to keys sharing a group. A synth or an effect cannot declare it; sample engines have their own chokeSameKey (see Services).

Holding the track key and choosing scramble re-rolls every key of a kit, as on Drumline: its model, from all the kit's models, and each control that model uses. The key's choke group, pan, level and pad fields (sends included) stay; a padMix key never edited is set up as an edit would set it up, at 0 dB with its fields neutral. A sounding voice plays the new values from its next block. A kit may keep scramble musical by narrowing the range a control is drawn from:

void scramble_range(opxy::u32 model, opxy::u32 slot, opxy::u8* low, opxy::u8* high);   // optional; in the machine namespace

low and high arrive as 0 and 127; narrow either, inclusive. A kit without it draws every control from 0..127.

A kit's engine may also report that a voice's sound has ended, so stock retires its note and the voice is free for the next one before stock's amplitude envelope ends:

bool finished(const Voice& voice, const Shared& shared);   // optional; in the machine namespace

The adapter asks after each rendered block. Once it returns true, the adapter calls destroy and frees the voice, and stock retires the note after mixing the block just rendered, so return true only once the voice renders silence. The function must be in the namespace that defines Voice, where argument-dependent lookup finds it, and take the voice and the shared state; one elsewhere or with other arguments is never called. A kit without it behaves exactly as before. The browser preview models neither the choke nor finished.

A kit declaring "sdk": "1.10" or later may also take the tempo:

void drum_transport(Voice&, Shared&, opxy::u32 owner, const opxy::Transport&);   // optional; in the machine namespace

The adapter calls it before every render, after drum_select and drum_pad, with the audio clock's advisory tempo, 96-PPQN ticks and play state, the same opxy::Transport sample engines get. bpm_x10 is 0 when there is no tempo. As with finished, argument-dependent lookup finds it in the namespace that defines Voice; include <opxy/transport.hpp> in the kit's source. It needs no resource: an SDK without it builds the same source and never calls it, nor does this SDK for a kit declaring an older version. Keep a fallback for when it is not called or bpm_x10 is 0, such as a tempo of the kit's own. The profiling workload passes 120 BPM, playing. The browser preview has no tempo and never calls it.

Kits use the same fixed shared-state and voice-pool rules as synths. Their code and state are linked once per machine, shared across tracks; voices still require independent state. Machine code and model data need no file loading when notes or patterns change.

Stock Drumline's second page

A drumline_page extension gives stock's own Drumline (engine 4) a second page of per-key settings on every Drumline track: a press of any encoder on the engine page switches to it. The extension declares one to four parameters and processes each hit's voice; the SDK keeps the page, the per-key storage, the per-hit latch, FX I and FX II as a padMix key's sends, and step locks. Without one, Drumline is stock's.

Sample engines

sample_engine.hpp defines the sample interface. A sample machine supplies sample.cpp with:

struct Voice { ... };
void initialize(Voice&, const opxy::SampleView&);
void start(Voice&);
void render_sample(Voice&, const opxy::SampleBlock&);

initialize receives the read-only sample stock assigned to the voice, which the SDK retains until the voice is destroyed; a view with no frames means silence. start runs on each note. Never retain a block or its buffers.

The stock sampler a sample engine forks (machine.json base) sets how it plays and which stock screen it uses. With "base": "sampler" it plays like the stock sampler: one sample, played chromatically across the keyboard, its root key playing it as recorded. With "base": "drumSampler" it plays like the stock drum sampler: 24 pads, each with its own sample.

Own screen

From SDK 1.8, a sample engine forking the sampler ("base": "sampler") may draw its own screen over the sampler's page, as a synth draws its page: it declares resources.display in definition.json and supplies display.cpp and panel.svg.fragment (Display API), and each build gives the screen a page as it gives a synth's (Identity). The screen covers the sampler's page whenever a track using the engine is selected and that page is showing; the stock sample browser and recorder keep their own pages. The encoders then edit the engine's controls as on a synth's page: a press switches between the first four controls and the second four, Shift turns a continuous control in fine steps, an enum steps one choice per detent, and edits are saved like a synth's. The engine plays the sample between its outer markers; inner loop markers do not narrow it. Display code can draw the sample from its overview.

What this gives up. The own screen takes over the sampler page's encoders, so the stock sampler's own controls are gone from it: a player can't set the sample's start and end, its loop, its gain or the other things that page's encoders edit, from there. SampleBlock.region still reports what the region holds: the whole sample when one is newly assigned, or whatever a preset or the same track on the stock sampler left. An instrument can give itself its own controls for these and read them in render_sample, or hand some of them back to the stock page with stockShift.

Stock controls on Shift (stockShift, SDK 1.10). resources.stockShift lists, for encoders 1 to 4 in order, which of the stock sampler page's controls Shift and that encoder edit. Stock then edits, steps and saves the setting with the track, as on its own page, and the engine reads it from SampleBlock.region:

Name Edits On the stock page Read from
start Sample start Encoder 1 region.begin
loopStart Loop start Encoder 2 region.loop_begin
loopEnd Loop end Encoder 3 region.loop_end
end Sample end Encoder 4 region.end
direction Forwards or backwards Shift + encoder 1 region.reverse
tune Tuning Shift + encoder 2 region.pitch_cents
gain Sample gain Shift + encoder 4 region.level
window The start and end together Encoders 1 and 4 region.begin, region.end
loopWindow The loop start and end together Encoders 2 and 3 region.loop_begin, region.loop_end
"" The machine's own control, in fine steps, as without stockShift

A window moves its two markers by the same turn, keeping its length, and stops at the sample's ends. Each name may appear once; a list shorter than four leaves the remaining encoders on fine steps. For example, a granular engine might choose:

"stockShift": ["start", "end", "window", "gain"]

and a looping one ["loopStart", "loopEnd", "loopWindow", "tune"]. Only Shift turns on the engine's own page change; everything else stays as it was:

  • Turns without Shift edit the machine's own controls, and a press still switches between its first four and second four.
  • An encoder the list leaves empty keeps Shift's fine turn of the machine's control.
  • The track's envelope, filter and LFO pages are stock's, with or without Shift.

The engine plays begin..end as before. The loop markers are reported for the engine to use as it chooses; stock's own loop does not apply to it. Stock's loop crossfade (Shift + encoder 3) and loop mode (Shift + encoder 3 press) aren't offered: SampleBlock doesn't carry them. stockShift needs an own screen and SDK 1.10. While Shift is held, the screen's input shift is 1, so it can show what Shift edits; the overview gives the start, the end and the gain. The stock sample browser and recorder are unaffected.

Services

Each service is an optional entry in definition.json resources; omitted means 0. Callbacks are functions in the machine's namespace.

Resource Value Effect Callbacks
stereoOutput 0 or 1 Output is 64 interleaved left/right frames
chokeSameKey 0 or 1 A note silences earlier voices on the same track and key (drum sampler base: the same pad, at any octave)
padControls Up to two {label, bits, signed} fields, 1..7 bits each (2..8 signed), 9 in all; needs padMix Each key's own small settings on Shift's second row (drum kits) drum_pad, pad_control_text
padMix 0 or 1; drum kits, SDK 1.10 Shift: the model, choke group and each key's stock pan and level; on the second row the key's pad controls and its own FX I and FX II sends; a held step locks pan, level, pad controls and sends per hit (drum kits)
padSettings 0 or 1; drum sampler base The SDK saves 18 machine-defined bits with each pad sample_defaults, sample_assign
drumControls 0 or 1; needs padSettings The drum page's machine encoders and panel drum_control, drum_panel
sliceTiming 0 or 1; needs drumControls and SDK 1.7 Lazy-chop audition through the machine, with a matching source-frame tap clock slice_clock
stockShift Up to four names, one per encoder; needs an own screen and SDK 1.10 Shift and those encoders edit the stock sampler page's controls (own screen)
sampleAnalysis Budget in bytes, 4096..2 MiB, whole words Prepared per-sample data analysis_words, prepare_begin, prepare_step, prepared

Audio block

SampleBlock field Contract
output 64 Q31 words, or with stereoOutput 64 interleaved left/right frames (128 words). Write every word
parameters The track's eight live Q31 parameters; the first are the declared controls
pitch 64 phase increments, as for a synth
transport Advisory project tempo, 96-PPQN tick and play state
region.begin, region.end The pad's trim, a half-open frame interval within the sample; empty means silence. With drumControls, the outer markers
region.level Unsigned Q27 gain; opxy::sample_unity_level is unity
region.reverse The pad's saved direction
region.pitch_cents The pad's saved tuning, in cents
region.loop_begin, region.loop_end SDK 1.10: the pad's loop markers, within the sample. No loop when loop_begin is at or past end; both are end where nothing sets a loop, as in a lazy-chop audition
analysis This machine's completed analysis of the sample, or null while pending, declined or over budget
settings The pad's saved settings, or sample_defaults() when it has none; 0 without padSettings
output_channels 1, or 2 with stereoOutput
track_transpose The track settings transpose, -36..36 semitones
drum_transpose Drum sampler base: semitones from the note's pad to the played note (whole octaves), fixed at note start. 0 with the sampler base
slicing A lazy-chop audition: traverse the supplied outer range once, forwards, using frozen settings, parameters and tempo. Ignore live trims, reverse and loop settings

Source and output channel counts are independent. Stock envelopes, mixing and project voice settings follow the callback.

Slice timing

void slice_clock(const opxy::SampleSlice&, opxy::SampleSliceRate&);

With sliceTiming, the GUI calls slice_clock with the loaded frame count and file rate, outer range, pad settings, eight live parameters, track transpose and project tempo captured when lazy chop starts. Return a nonnegative numerator and positive denominator and tuning: source frames per 44.1 kHz output frame are numerator / denominator * tuning / 4096. Account for the same timing and pitch arithmetic as the audio renderer. This callback accesses no PCM or analysis.

The SDK sends the frozen configuration with the audition note. Audio receives it in SampleBlock with slicing=true, transport stopped at tick zero, and drum transpose zero. Subsequent cuts cannot change the audition range; control, automation and master-tempo edits apply to the next audition. A renderer that waits for analysis must keep the audition's source clock advancing while silent, then resume at its elapsed position. Without this service, lazy chop uses one forward pass of raw PCM at the original file rate. Ordinary notes use normal machine playback.

Pad settings

PadSettings is an unsigned value from 0 to 262143 (18 bits), stored in a u32 since SDK 1.6. The SDK reads existing 16-bit settings without changing their values. Machines using values above 65535 must target SDK 1.6 or later; firmware built with older SDKs cannot read those extended values.

opxy::PadSettings sample_defaults();
opxy::PadSettings sample_assign(const opxy::SampleAssignment&);

sample_defaults returns the settings of a pad that has none. sample_assign runs when a file or a completed stock recording (recorded) is assigned to a pad and returns the pad's new settings. It receives the file path (filename_bytes long, not NUL-terminated, possibly null; null for a recording), the loaded frame count and rate, the project tempo, and in previous the settings of the pad's replaced sample (replacing) or the defaults. The new sample's trim spans its whole length; a replaced pad keeps its pitch, reverse and volume. Settings survive project save exactly.

Drum page

void drum_control(opxy::PadSettings&, const opxy::DrumControl&);
void drum_panel(opxy::PadSettings, const opxy::SampleRegion& saved, opxy::Parameters live, opxy::DrumPanel&);
Encoder Main Shift
1 Pad pitch: ±12 semitones in ten-cent steps; press resets Stock reverse
2 Stock start marker Machine, knob 1
3 Stock end marker Machine, knob 2
4 Machine, knob 3 Stock volume

drum_control receives each turn (signed direction) or press of a machine encoder, with shifted set on the Shift row, and edits the settings. held marks a turn while the encoder is held down; turning suppresses the click on release. Machines decide how that gesture changes their stepping. drum_panel receives the settings, the pad's saved region and the eight live parameters audio uses, and reports the pad as the machine plays it: the live pitch offset in cents (the page adds the pad's saved pitch), loop or play once, direction, a Q31 scale of the saved volume, and two Shift captions of at most 15 characters, which replace the pan row. The panel arrives with pitch 0, the saved direction and an unchanged level, so a machine sets what its controls change. On the drum page saved.level is unity: stock keeps the pad's volume separately, and level scales it. The SDK only projects the panel onto the stock page, so a machine applies its live controls in one place for display and audio. Callbacks are bounded and allocation-free.

Stock's page reads slots 0 to 3 as pitch, start, end and play mode. The SDK replaces pitch and play mode with the panel's, so only slots 1 and 2, the start and end trim overlays, reach stock directly; slot 0 keeps stock's ten-cent pitch editing, -12..12 semitones. The machine defines the remaining slots in definition.json. See Timestretch.

Sample analysis

struct Preparation { ... };
opxy::u32 analysis_words(const opxy::SampleView&);
bool prepare_begin(Preparation&, const opxy::SampleView&, opxy::u32* storage, opxy::u32 words);
opxy::PrepareStatus prepare_step(Preparation&, opxy::u32 frames, opxy::u32& cursor);
bool prepared(const Preparation&, opxy::SampleAnalysis&);

sample_analysis.hpp defines the types. After a file is assigned to a pad, the SDK asks each analysis machine how many words the sample needs (0 declines), allocates them from the stock heap within that machine's budget, and runs prepare_step in bounded chunks on the stock file worker until prepared publishes the immutable result. Nothing is prepared while the sample browser is open, and a sample that does not fit stays unanalyzed. Results are released before stock frees the sample. A collection's analysis budgets together may not exceed 2 MiB.

Effects

effect.hpp defines the effect interface. An effect supplies fx.cpp, which includes its core.h, with these callbacks in its namespace:

struct State { ... };
void initialize(State& state);
void process(State& state, opxy::Channel left, opxy::Channel right,
             opxy::Parameters parameters);

Stock constructs an effect in place in its send slot on the audio thread and calls initialize, which runs again on an engine reset, so keep it short; storage starts zeroed. process runs once per 64-frame block on the stereo send buffers and replaces them in place: left and right are distinct 64-word Q31 buffers. parameters holds the stock eight-word vector of normalized Q31 words; the first are the one to eight declared controls. Do not depend on the absolute level of the send buffers.

State is at most opxy::effect_state_bytes (476) with alignment at most 4. No destructor ever runs, so it holds no resources. The generated adapter checks both limits at compile time. Effects use the stock FX page, with any controls after the fourth as alternates or a second page, and have no browser preview.

Effect pages and shift rows

An effect with five to eight controls may declare "press": "page" (SDK 1.7), as a synth does: a press of any encoder on its send page switches all four positions between its first four controls and the rest.

An effect may also declare a shift row (SDK 1.7): one to four enum controls in "shift" in definition.json, which Shift and the send page's four encoders choose, one choice per detent, while the page shows their names and choices. They suit routing and modes, such as an order or a source. All their choices together are at most 1,048,576 combinations; the first choice of each is what a new project starts with. With a shift row, Shift no longer turns the effect's continuous controls in fine steps.

process then receives twelve words: the eight controls, then each shift-row control's chosen word, read as any enum control:

"shift": [
  {"id": "order", "label": "Order", "default": 0, "display": "enum",
   "mapping": {"kind": "enum", "labels": ["TPES", "TEPS", "PTES"]}}
]
const opxy::u32 order = ((static_cast<opxy::u32>(parameters[8]) >> 16) * 3) >> 15;

Its State is then 4 bytes smaller than otherwise (the slot keeps the send's number). See the firmware contract.

Effect pages

An effect may draw its own page on the send tracks (SDK 1.7): it declares resources.display and supplies display.h, display.cpp and panel.svg.fragment, exactly as a synth does (display API). Each build's layout then gives it a page from 82..255 beside its effect number, as it gives a synth its own. Stock shows the page an effect's record names on M1 of a send, so the page replaces stock's FX page there; its header names and captions the effect's controls, or its shift row's while Shift is held, and the display reads them all, the shift row too (input). Effects have no browser preview yet. An effect that comes to draw its own page keeps its effect number and is given a page in its firmware's layout.

Effect buffers

An effect that needs memory beyond its state, such as a delay line, declares "bufferBytes" in definition.json resources: whole words, at most 524288 (512 KiB). It needs "sdk": "1.2" in machine.json, and its process takes the buffer:

void process(State& state, opxy::Buffer buffer, opxy::Channel left,
             opxy::Channel right, opxy::Parameters parameters);

buffer.words is the send slot's scratch memory, buffer.count words long; stock delay and reverb use the same memory. Its State is at most opxy::effect_buffered_state_bytes (472). The buffer:

  • Is never cleared: it holds whatever the slot's previous effect, or this one before an engine reset, left. Read only what the effect has written since initialize, for example by counting the words written.
  • Is empty outside a send: buffer.words is null and buffer.count 0; write silence then.
  • Is per send: an effect on both sends gets two buffers.

Tempo

An effect declares "transport": 1 in resources (SDK 1.2) to receive the audio clock's tempo, read once per block, after the buffer if it has one:

void process(State& state, opxy::Buffer buffer, const opxy::Transport& transport,
             opxy::Channel left, opxy::Channel right, opxy::Parameters parameters);

transport.bpm_x10 is the tempo in tenths of BPM, or 0 when there is none (see opxy/transport.hpp). Sample engines get the same transport in their SampleBlock, and drum kits through drum_transport. A control with "display": "division" and a linear 0..1 mapping picks one of stock delay's note lengths, an eighth of its travel each: 1/32, 1/32 dotted, 1/16, 1/16 dotted, 1/8, 1/8 dotted, 1/4 and 1/2. opxy::division(control) gives the index and opxy::division_sixteenths the length in sixteenths of a quarter note, and the send page shows the length's name in place of the number, as for stock delay's Size.

process writes only the wet return. An effect may declare dryParameter in machine.json, naming a control with a linear 0..1 mapping. The adapter returns that control's raw Q31 word to the stock source mixer. Raising it restores dry source level without reducing the wet return. For one isolated send with effective send weight s and Dry d, the source dry factor is 1 - s*(1-d). At full send, Dry zero removes the source dry and Dry one retains it; at zero send, dry stays unchanged. Do not add clean audio inside process to implement this control. Without dryParameter, the adapter returns unity to preserve the source dry. Instead, an effect may fix its Dry with dryLevel in machine.json (SDK 1.7), a number from 0 to 1. An effect that mixes its own dry, as a box of effects inline does, declares 0: at full send a track then goes wholly through it.

Registration boundary

A machine's ID (definition.json's id) is its stock name: the engine type the device lists, its catalog and preset entries, its screen file, its symbol prefix and its C++ namespace. It is a lowercase letter followed by letters, digits or _, at most 15 characters. It may not be a stock engine or effect type, a C++ keyword, opxy or std, or start with a reserved prefix (extensions, sdk, kit, stock, local).

machine.json declares how the SDK builds the machine:

Field Contract
schema 1
sdk The SDK version the machine targets, "<major>.<minor>". This SDK is 1.13 and builds 1.0 to 1.13 machines
kind synth, drum, sample, effect or player
description Plain text of at most 160 characters, shown by the builder and preview
base Sample engines only, and required for them: the stock sampler it forks, "sampler" or "drumSampler" (sample engines)
sources, includes Optional extra translation units and include folders inside the machine folder; synths only, since the native plan compiles one source for the other kinds
icon Optional builder glyph: SVG path data in a 46 × 48 box, drawn as a stroke. The kind's glyph is used otherwise
presetDefaults Optional {"amp": {...}} overriding generated factory preset envelope values: attack, decay, release and sustain, each 0..32767. It does not rewrite existing projects or presets
presets Optional folder inside the machine folder holding the machine's own presets; sdk 1.3, instruments only
samples Optional folder inside the machine folder holding a sample engine's own samples, which its presets load; sdk 1.10, sample engines forking the sampler
graphics Optional {"grayscale": "panel.grayscale.svg.fragment"} for a synth's developer-authored grayscale artwork; sdk 1.5

An effect's optional dryParameter field names the control used by the stock source dry mixer, as described under effects.

Presets

The builder installs an init preset for each instrument, content/presets/<id>/default.json, from its control defaults and presetDefaults. A machine can ship its own: save them on an OP-XY running firmware with the machine, copy the preset files into the folder presets names, and the builder installs each <name>.json as content/presets/<id>/<name>.json. A default.json there replaces the generated init preset. Presets store the machine's ID, so they work in any firmware that holds it.

  • A name is lowercase letters, digits, - and _, at most 24. Other files in the folder, except .md and hidden files, are refused.
  • At most 16 presets, each at most 16 KiB.
  • Each is a version 4 OP-XY preset whose type is the machine's ID, with eight engine params from 0 to 32767 and no sample regions, since a preset never points into a user's sample library. A sample engine shipping its own samples may point at those instead. Other fields stay as the device saved them, except that a synth with a Shift row keeps it in up to 24 regions that point at no sample.

Own samples

From SDK 1.10 a sample engine forking the sampler ("base": "sampler") can ship samples of its own, so its init preset and its other presets open with a sound loaded instead of an empty track. machine.json samples names a folder of <name>.wav files, and sdk.py build installs each as content/samples/<id>/<name>.wav. They live in the OP-XY's content storage, not in the module memory: stock loads one into its sample memory when a preset pointing at it is loaded, as it loads any other sample, and the player can still load another sample over it.

Ship only audio you made yourself or may redistribute under the machine's licence: never the OP-XY's own content, and no commercial, library or other third-party sounds you can't relicense. Say in a README.md in the samples folder where each sample comes from, how it was made and under which licence it ships. Catalog review checks it.

  • A name is lowercase letters, digits, - and _, at most 24. Other files in the folder, except .md and hidden files, are refused.
  • At most 4 samples, each at most 2 MiB: a WAV file of plain 16-bit PCM (format 1, not WAVE_FORMAT_EXTENSIBLE) at 44.1 kHz, mono or stereo.
  • Every sample is loaded by at least one of the machine's presets, so samples needs presets.
  • A preset points at one in its single sampler region, as stock saves a sample engine's preset. Its sample is the installed path, content/samples/<id>/<name>.wav; its framecount is the sample's frame count; sample.start (0 if absent) and sample.end lie inside it, and the loop markers inside them. pitch.keycenter and hikey are 0..127, gain is -30..20 dB, and reverse and the loop flags are true or false. tune, pan, fade.in, fade.out and loop.crossfade stay 0: the SDK doesn't record their saved ranges yet.
  • Presets name the file, so it is installed once however many presets use it. A machine without samples keeps empty regions.
  • Projects and presets name a sample by its path. Treat a shipped sample as fixed: replacing or removing it under the same name changes or silences every project and preset that loads it, and builds never delete files an earlier build installed. Give new or changed audio a new name.
  • The files share content/samples/ with whatever else is on the OP-XY. The SDK doesn't record the names of stock's own sample folders, so it can't refuse a machine ID that matches one: check the device's /content/samples/ before choosing a sample engine's ID.
  • The browser builder doesn't install samples yet. Its kit still offers the machine and its presets, but not the samples: there each preset opens with no sample loaded, as a sample engine's presets did before. sdk.py build installs the samples and the presets as they are.
"regions": [{"sample": "content/samples/mysampler/pad.wav", "framecount": 264600,
  "sample.start": 0, "sample.end": 264600, "pitch.keycenter": 48, "hikey": 127,
  "gain": 0, "tune": 0, "reverse": false, "loop.start": 0, "loop.end": 264600,
  "loop.crossfade": 0, "loop.onrelease": false}]

Identity

A machine is identified by its definition.json id. Presets save that name, so it never changes once published. machine.json holds no numbers: each build gives every machine the stock numbers projects save, an engine number (an effect number for an effect) and a screen number, and keeps them.

Kind Engine or effect number Screen
synth Engine 34..255 Its own, 82..255
sample Engine 34..255 Its base's: the stock sampler's or drum sampler's. An own screen: its own, 82..255
effect Effect 1, 8, 11, 21, 23..28 or 34..62 The stock FX screen, or its own, 82..255 (SDK 1.7)

These numbers exist only in the relocated stock tables, so no machine shares one with stock. Four core machines, which the first Open-XY firmware shipped, have fixed numbers held in every firmware whether it includes them or not (FIXED_NUMBERS in tooling/machines.py). Every other machine is numbered by the firmware's layout: its record of every number it has given out, including to machines since dropped, which stay held so an old project never opens another machine. The builder and sdk.py build write the layout after each build to layout.json; give it to the next build so every machine keeps its numbers. A machine new to the layout gets numbers from its own place in each pool above, worked out from its ID (FNV-1a, 32-bit, of the ID's UTF-8 bytes, modulo the pool's size), or the next free number above it, wrapping around. Machines are numbered in ID order, never collection or selection order, so even a build without a layout gives a machine the same numbers whatever else it includes, unless another machine's place collides with its own: then the first by ID keeps it. Only a layout guarantees numbers. A sample engine's own screen takes a page as a synth's does, and one that gains a screen keeps its engine number and is given a page. A project companion records what a project's numbers meant by machine ID, so Open-XY firmware with another layout opens the project with the same machines.

Machines targeting SDK 1.4 or earlier instead list the numbers they ask for in identity, {"engine": n, "page": p} or {"effect": n, "page": 21}, and name no base. A layout gives them when free, before any machine's own place, otherwise numbers as for any other machine; a sample engine's page 2 forks the sampler and 7 the drum sampler. Such a machine keeps working unchanged. To move it to "sdk": "1.5", delete identity and, for a sample engine, add its base; a 1.5 machine with identity is refused. Its numbers in an existing layout.json stay its own, so build with the previous layout.

Generated adapters check record/name ownership and screen readiness before catalog admission; the packager authenticates firmware and constrains writes. See native builds. Generated instrument presets use polyphonic voice mode.

Arbitrary external-engine loading is not implemented: a machine reaches the firmware through the collection, from the catalog or as a folder passed to a build with --machine.

Note players

SDK 1.8 adds "kind": "player". A player transforms live and sequenced notes before the track's instrument receives them. Its machine.json declares no identity or base; the layout assigns an unused player type and its own page. Use four parameters, "resources": {}, player.cpp and panel.svg.fragment. A parameter an encoder doesn't need may be left empty, declared "absent": true as for a synth's empty slot: its title and value stay empty and its encoder turns nothing. Players have no instrument presets, audio-render CPU estimate or browser audio preview.

Include <opxy/player.hpp> and implement, in the machine's namespace:

struct State { /* zero-initialized, at most 2048 bytes, alignment at most 4 */ };
bool press(State&, const opxy::player::Controls&, opxy::u32 note,
           opxy::u32 velocity, opxy::player::Plan&);
bool release(State&, opxy::u32 note);
void display(const State&, const opxy::player::Controls&, opxy::player::Display&);

press returns false to pass a note through, or true with a plan of zero to eight tones. Each tone has a MIDI pitch and velocity, and a delay in stock player steps. Zero sounds on the next step. A plan's tones release together with its root; at most eight roots can be held. A ninth plan is dropped. release returns true for a silent control key, false to let stock release its chord. Note callbacks do not allocate, block, log, perform I/O or draw. State holds no resources. Display reads are advisory while sequencing runs.

For live changes to held chords, optionally implement bool update(State&, const Controls&, Update&). After a taken press or any release, and before every stock player step, the SDK drains at most eight updates, stopping when it returns false. Calls run on the sequencer role, so held chords can follow control changes without GUI-side note operations. An update names an existing root, a plan, and mode Replace or Add. Replace releases the old tones and schedules the new plan; an empty plan silences that root. Add keeps sounding and queued tones and appends only new pitches, up to eight total. A change never starts a root with no current record. Invalid MIDI values or counts discard the update without changing the chord. Cleared records are immediately reusable, including at capacity.

Optional void reset(State&) clears held inputs after stock reset or all-notes-off; it can preserve machine settings. Without it, the SDK zeroes State. Keep machine root tracking bounded to eight and clear it on root release and reset. These callbacks share the same restrictions as press.

Controls.value contains the four Q31 parameter words. Declared enums with 2..255 choices move one choice per encoder detent, storing the choice's centre. Other mappings retain the Maestro controller's editing: 64 steps, four choices, continuous, and off/on, respectively. lowest_key is the track keyboard's lowest F at its current octave. Stock's octave setter publishes this independently of sample-engine selection.

The page keeps the stock header and uses the four definition labels. Display.values supplies their text; lit shows the 24 <id>_dot_0..23 circles or filled paths; text replaces the centered <id>_text text leaf. All strings must terminate within their fixed arrays. The SDK then fills played[4] from emitted, still-held stock chord records, ignoring queued strum tones, and supplies lowest_key for the output keyboard.

The output keyboard is optional: omit all its key and activity nodes for an input-only page. When present, it binds <id>_key_0..127 paths and <id>_played_0..127 circles or filled paths. Author white keys as 10 by 44 paths and black keys as 6 by 27 paths at the origin, white keys before black keys in SVG order, then activity dots. Use explicit fill and stroke and a matrix(1 0 0 1 x y) transform on every binding. The SDK lays out these keys in the lower 444-pixel-wide row at y=174, fitting whole F-to-E octaves around the input keyboard and every emitted note. This preserves octaves under voicing, spread and simultaneous chords. MIDI endpoints use partial octaves. Hidden nodes move beyond the display.

Player types remain stable when a subsequent build uses the saved layout. Stock firmware replaces an unknown saved player with Arpeggio. Project companions currently describe engine/effect identities only: preserve the firmware's layout.json for player identities.