SuperDirtMora class reference

SuperDirtMora is Mora’s SuperDirt companion package: a SuperCollider class that packages Mora’s existing SuperCollider extensions. It is not a replacement audio engine. This page lists its methods, arguments, and ownership contracts; for the Lisp side of the same features, see SuperDirtMora companion.

Related SuperCollider classes: SuperDirt, Quarks.

The package is built in the Mora checkout and installed as a Quark:

1. Build the self-contained package with make superdirt-package in the Mora checkout.
2. Install the printed package directory with the Quarks.install class method.
3. Recompile the class library during setup, not during a performance.

Do not install the source template directory. The build adds the canonical resources from Mora’s sc/ and scd/ directories.

SuperDirtMora works with an existing SuperDirt setup; see Installation and setup for SuperCollider and SuperDirt. Use one language interpreter and one audio server.

Construct one owner for that Dirt and attach the core:

~mora = SuperDirtMora(~dirt);
~mora.attach; // core amplitude/ordered-FX language integration
~mora.status.postln;

Construction installs nothing. attach with no argument requests the default core component, which installs the acknowledged amplitude/FX language protocols. status reports detached request state; a requested component is not necessarily ready.

Optional features are explicit. Pass their component symbols to attach:

~mora.attach(#[mixer, scope]);

A repeated request on the same owner does not reload its feature script. Retain one owner per Dirt, and do not combine package activation with the old individual startup loads. The supported components are listed under SuperDirtMora.components.

For sample loops, attach the loop-aware path before core startup, instead of the initial ~mora.attach. Its source policy is mandatory: ownedBuffer must reverse-resolve every held managed Buffer from the actual sample owner, including staged/uncertain reservations. Pass that owner’s original Function, not an incomplete second registry. No ownership Function is downloaded or accepted over OSC. Retain the same Function for repeated calls.

~mora = SuperDirtMora(~dirt);
~mora.attachSampleLoops(~sampleOwnerOwnedBuffer, ~sampleOwnerLoopAdmission);
~mora.attachModulation; // optional continuous-control/play receivers; no native DSP yet
~mora.installDucking; // optional DUCK control service; native stages remain lazy
~mora.sampleLoopStatus.postln;
~mora.modulationStatus.postln;

The two policy variables above are caller-provided local Functions, not shipped globals. A setup with no managed buffers may explicitly supply a Function returning nil for every buffer; that assertion must remain true for all aliases. Omitting managed admission refuses managed sources.

This installs only language protocols and adopts them through normal core startup. Native loop readers are prepared later by Mora’s explicit prepare-audio, never while rendering or sending an event. A running AMP/FX generation is never silently replaced.

To make continuous-control services survive restarts, keep the explicit attachModulation call after attachSampleLoops in the normal SuperCollider startup. An old installed package must first be updated and its class library recompiled; do not patch a running old AMP/loop graph.

SuperDirtMora.new(dirt, environment)

• dirt: An existing SuperDirt. Construction installs nothing.
• environment: The existing environment containing that exact dirt as ~dirt. Defaults to currentEnvironment; no environment/global server is replaced.

Returns the supported component symbols.

The examples on this page pass the lowercase symbols core, mixer and scope; call SuperDirtMora.components for the exact supported symbols. The Lisp-side generation and neural-instrument paths are described in Generation and neural instruments.

The package also ships the definition-only sample-loop reader, source and protocol factories and MoraSampleLoopEvent preparation. Loading these does not install a new sample/event route. They are described under Internal mechanisms.

SuperDirtMora.at(dirt)

Retrieves the retained package owner for this dirt, or nil before activation. Ownership is per Dirt, not merely per Environment; a second environment cannot install another copy. Owners with potentially active resources are not evicted.

Internal ownership guard used before definition loading and attachment. It does not install protocols or claim native readiness. Use new/attach rather than calling this implementation method directly.

Returns this installed package’s root, derived from the class source location.

SuperDirtMora.resourcePath(relative)

• relative: One exact shipped resource name. Arbitrary filesystem paths are refused.

Instance methods are called on an owner, such as ~mora in the examples above.

attach(features)

• features: Unique Array of component Symbols, default #[core].

Requires the exact existing environment/Dirt and running server/orbits. Legacy server-bound features also require that server to be Server.default; attachment never changes it. The operation is not a rollback transaction: failure is recorded, not blindly retried after possible partial resource acquisition. Use status to inspect.

attachSampleLoops(ownedBuffer, managedAdmission, reviewedCatalogue, trustedReceiverHooks)

• ownedBuffer: Required bounded, non-yielding Function reverse-resolving all held managed buffers from the authoritative owner. It is called with the buffer number; return the exact retained ownership object, or nil to assert external ownership.
• managedAdmission: Optional bounded, non-yielding Function approving each managed reader, including aliases, against that owner’s actual lifetime policy. It is called with phase (\prepare or \play), ownership object, Event and reader profile (nil at prepare). Return literal true to approve. Omission refuses them.
• reviewedCatalogue: Optional explicit amplitude source catalogue. Defaults to the reviewed current SuperDirt sample/SynthDesc catalogue, without loading or importing any sample.
• trustedReceiverHooks: Optional explicit amplitude receiver-hook approvals. No hook is approved by default and output routing remains unchanged.

Constructs and retains one exact source, native-definition, dispatch, AMP, FX and loop-protocol graph; normal core startup then adopts it. Repeating with the identical policy and a healthy protocol is idempotent. Changed policies, stale owners and partial failures refuse blind retry. Retained failures require explicit reconciliation: the method never automatically restarts a server, recompiles classes, frees resources or rolls back another owner’s state. Installation grants no native reader readiness.

sampleLoopStatus

Returns detached language attachment state, protocol readiness and native reader phase/readiness. protocolReady reports the language protocol only; prepared readers and native reader readiness are reported separately.

attachModulation

Explicitly attaches the continuous-control v3 service and protected prepared-voice play receiver to this owner’s current sample-loop/AMP graph. Call attachSampleLoops first. The package composes a dormant voice ingress during that earlier attachment; this method never patches an old installed dispatcher or adopts foreign responders.

The same native control journal owns the clock, stable shared bindings and prepared voice registry. Installation acquires language receivers only. It does not allocate a native clock, control/audio bus, source, buffer, voice program or notification listener. Those await explicit preparation through Mora.

Repeating a healthy attachment retains the same owners. Existing reserved routes, missing composition, and failed/stale/closed attachments refuse rather than retry or replace uncertain resources. A partial returned control owner is retained for inspection even if a later install step fails. Optional service failure leaves ordinary AMP/loop ownership unchanged.

With the existing Dirt and authoritative buffer-owner Function established by startup, the package setup is:

~mora.attachSampleLoops(~moraLoopBufferOwner).attachModulation;
~mora.modulationStatus.postln;

Do not call attachModulation after independently installing a different AMP/loop owner.

modulationStatus

Returns a detached cached summary: phase, protocolReady, nativeClockPhase, nativeClockReady, voicePrograms and voicesCovered. Protocol availability is separate from source approval and native voice playability. This query performs no native readback, preparation, resource cleanup or routing change.

Loading definitions or constructing the package starts no duck processor and allocates no duck audio/control bus.

Ducking is driven either by the control service that installDucking installs or by the manual prepare/enqueue/drain/close methods; installDucking describes how the two interact.

installDucking

Installs five loopback-only control/trigger receivers on the existing Dirt port. This is idempotent and does not prepare a definition, allocate a bus, start a processor or change routing. Explicit prepare/close requests use one retained operation receipt and a stable lease; a failed/uncertain operation cannot be silently replaced. The native owner is the same one inspected by duckingStatus.

While this service exists, the manual prepare/enqueue/drain/close methods refuse a competing controller. Close an existing manual duck lifetime before attaching the protocol; queued manual jobs and active processors are never silently adopted by a newly minted control lease.

~mora.installDucking;
~mora.duckingControlStatus.postln;

The version-one wire service uses /mora/duck/capabilities, /mora/duck/command, /mora/duck/request, /mora/duck/ack and /mora/duck/batch. Replies use /mora/duck/reply.

• Every request has a protocol version and exact service epoch; mutations also need the retained lease and ticket/sequence.
• A batch is a single completed scheduler cohort, anchored by its OSC bundle timestamp with small per-trigger second offsets. It introduces no extra trigger-buffer timer.
• Duplicate or late sequences never replay; sequence gaps are accepted after UDP loss.
• Ambiguous native publication seals trigger admission and retains ownership for explicit cleanup.
• Packet, field, job and target limits are advertised.
• After closure is proved and its receipt acknowledged, an explicit prepare with a fresh lease starts the next native lifetime without reinstalling the receiver. Old leases and their delayed trigger packets cannot enter that new lifetime.

duckingControlStatus

Inspects detached receiver coverage, epoch context, receipt occupancy, lease, trigger admission, native-owner facts and separate batch/job/failure counters. This reads cached state only. Receiver installation and native DSP readiness are reported separately.

uninstallDucking

Detaches only the exact owned receivers. Refuses while any operation receipt is held or native ownership has not been proved closed; close and acknowledge the terminal receipt first. A failed detach leaves the service inspectable; it does not discard an uncertain native owner or allocate a replacement.

checkManualDucking

Internal controller guard. Manual native methods refuse while the protocol service owns this package’s ducking lifetime; this method acquires no resource.

prepareDucking(timeout)

• timeout: Acknowledgement budget in seconds, greater than zero and at most thirty. Defaults to three seconds.

Prepares on an off-frame Routine. Queries the existing Dirt output monitors for their actual native parents, registers exact node-lifetime notifications, and acknowledges one private SynthDef. No processor starts until a trigger is drained. Failed preparation retains its owner for explicit closure; repeated calls do not blindly repeat partial work. Proven full closure permits a new generation.

fork {
    ~mora.prepareDucking;
    ~mora.duckingStatus.postln;
};

duckingStatus

Returns detached phase, readiness, target count, possible-node and definition state, notification cleanup and timeline status. No native query or preparation is performed.

enqueueDuck(time, rows)

• time: Absolute deadline in Main.elapsedTime seconds.
• rows: Array of [zeroBasedOrbit, depth, onsetSeconds, recoverySeconds] rows.

Adds planned state only; no native processor or packet is created here. Collect simultaneous triggers before draining. The same target’s already-published deadline cannot be reused in another publication batch.

Overlapping triggers resolve from their scheduled current gain; a weaker trigger never initially raises an already-suppressed target.

drainDucks(through)

• through: Drain watermark in absolute Main.elapsedTime seconds. Trigger deadlines must still be at least 2 ms in the future and at most sixteen seconds ahead when published. Later queued work remains planned, not submitted.

Publishes queued triggers through the explicit deadline. Each processor runs after the existing orbit effects, before its output monitor, multiplying exact dry/effect buses without changing routing or continuous mixer/crossfade state. No compilation or preparation occurs here.

closeDucking(timeout)

• timeout: Acknowledgement budget in seconds, greater than zero and at most thirty. Defaults to three seconds. Repeated closure may consume a late exact reply.

Closes on an off-frame Routine. Seals ingress, cancels unpublished work, schedules owned-node retirement after queued creations, and requires observed start/end notifications before freeing the private definition. Missing proof retains inspectable state. Timeout is not closure and does not replay uncertain writes.

fork { ~mora.closeDucking; ~mora.duckingStatus.postln };

Orbit taps measure private orbit dry buses for Mora’s measured listening; for the Lisp side, see Machine listening.

installOrbitTaps

~mora.installOrbitTaps;
~mora.orbitTapStatus;

Installation adds local control receivers only. An explicit client preparation acquires one small mono buffer and one silent capture node per selected orbit (up to eight). The private orbit dry bus is measured before orbit-global effects and the DAW. Several stems sharing an orbit are measured together. Audio input and hardware output routing are not changed. Views never start capture.

Each requested window is frozen until bounded sample transfers finish. Expired leases release only this owner’s resources; uncertain cleanup retains its reservation and refuses replacement. Close active taps from Mora and confirm release before ~mora.uninstallOrbitTaps. This method refuses to discard active or uncertain ownership. Installing or recompiling this package is a separate setup operation; no view performs it automatically.

orbitTapStatus

Returns detached control-installation, capture phase, frame/rate and resource identity information. Installation is not native preparation or active capture.

uninstallOrbitTaps

Removes this owner’s control/notification receivers after all client resources are confirmed closed. Refuses active or uncertain ownership. Does not stop Dirt, free somebody else’s nodes or alter routing.

The package also ships definition-only factories. The explicit attachSampleLoops method composes the sample-loop owners described below, and the package composes a dormant voice ingress during that same attachment. This section documents their contracts; loading these definitions does not install a new sample/event route.

Do not send ignored loop controls to an ordinary stock reader. Managed native-reader lifetime and retirement remain separate from language protocol installation.

After loadDefinitions, the reader’s internal constructor is ~moraMakeSampleLoopDefinition.(name, sampleChannels, outputChannels). It returns an uninstalled SynthDef; it does not call add or create a voice.

• Sample channels must be 1 through SuperDirt.maxSampleNumChannels, and output channels 1 through 16.
• The reader uses cubic interpolation, original-recording loop coordinates, fixed playback direction and a rate ramp over sustain.
• Hard wrapping is intentional; seam crossfading and pitch-preserving stretch are not supplied by this factory.

The event adapter must validate buffer dimensions, finite bounds and rate direction; constructing a SynthDef does not perform these checks.

The definition-only local dispatcher is constructed with ~moraMakeSampleLoopDispatcher.(dirt, nativeReady, admit). The resource owner must supply bounded, non-yielding functions establishing actual reader readiness and source admission. The dispatcher is not an OSC endpoint or an installer.

• Its non-reentrant withLoop scope admits one synchronous request; sequential requests may create independently playing voices.
• Private tokens are identity-bound, consumed once and removed on return or exception. They never cross OSC.
• The adapter preserves the exact stock receiver and global module list; only an admitted loop gets a private sound module. Ordinary protected events retain their existing path even when loop admission is closed.
• An explicit amplitude-protocol constructor argument binds this adapter’s exact Dirt, server, dispatch and readiness identities. Nothing attaches implicitly.
• Current loop admission requires a nil receiveAction.

The native definition owner is a separate internal factory: ~moraMakeSampleLoopNativeOwner.(dirt, epoch, sourceAdmission). Construction does no server work.

• Calling its prepare Function explicitly submits one private reader definition per supported source width.
• Readiness requires every exact completion acknowledgement before the bounded deadline; an entry in SynthDescLib is not sufficient.
• Repeated preparation reuses pending or ready work, and never silently retries an uncertain submission. Prepare belongs off the performance scheduling path.
• Server boot/quit/tree, allocator, library, channel/rate or factory changes invalidate the generation.

Its sourceAdmission Function receives reader name, input channels, output channels, low bound, high bound and the incoming Event before source merge. It must be a bounded, read-only, non-yielding lookup of the exact approved source and return literal true. Native definition readiness does not grant permission for a sample, import, managed buffer or retirement. Pass the owner’s original ready and admit Functions directly into the dispatcher, not mutable forwarding wrappers. No Function is supplied over OSC.

Close never frees a sample, node or definition, and cleanup uncertainty remains visible.

The source factory is ~moraMakeSampleLoopSources.(dirt, ownedBuffer, managedAdmission). Bind its result once to the installed amplitude owner using its bind Function.

The required ownedBuffer callback reverse-resolves every held managed buffer from the existing resource owner, including staged or uncertain allocations. Managed buffers and aliases also require explicit managedAdmission approval; omitting that callback refuses them rather than inventing retirement coverage.

For the packaged sample importer, use owner.attachSampleImports(receiver) before starting the core. The receiver must already be installed for the exact Dirt/server generation. Its reverse lookup includes staged and uncertain reservations, but admission permits only verified, committed, still-published buffers. This borrows the existing receiver’s conservative retention lifetime: committed abort/close still refuse, and no second buffer owner or retirement path is created. Allocator/server/publication changes invalidate new readers.

Legacy sample sources still pass through the actual amplitude/library policy.

• Prepare snapshots exact buffer, library-row, frame, channel and sample-rate facts off the scheduling path.
• Resolve and admit require a current five-second lease and refuse metadata drift.
• Source admission performs no file or server IO and does not free buffers.
• Its bounded route table holds at most 256 entries.

The control factory is ~moraMakeSampleLoopProtocol.(dirt, sources, native, dispatcher, amplitude, fx). It verifies that each owner’s original Functions form the actual protected playback path.

Its explicit installOSC Function acquires three dedicated routes. Pre-existing responder names refuse installation without replacement.

An invalid loop never falls through to non-looping stock playback.

Close releases only this adapter’s unchanged owned responders, preserves the other owners and reports uncertain cleanup.

Definition loading also provides ~moraMakeModulatedIngress and ~moraMakeModulatedVoicePlayback. Loading these Functions creates no receiver, source, program or native resource.

Construct the ingress before the protected AMP owner, passing its decorate Function to the sample-loop dispatcher’s constructor. Bind the resulting exact AMP and dispatcher with bind after installation. This preserves the original ordinary/loop dispatcher and uses AMP’s actual post-merge source-frame validator. Do not patch an installed dispatcher.

The playback factory accepts Dirt, a distinct play epoch, the existing v3 modulation control owner, bound ingress and AMP, plus paired optional source and native-loop owners. Its explicit installOSC installs only /mora/voice/capabilities and /mora/voice/play. Capabilities name the current play, control, AMP and optional loop epochs; they do not replace the separate source, prepared-program or native-lifetime admission checks.

The bounded music packet carries the prepared token and every current numeric control/FX binding, followed by either a note or an admitted loop envelope and ordinary protected event fields. It does not carry Lisp/native callbacks or prepare a source/program. Native reservation still precedes the actual Dirt bundle. The original timestamp, AMP scaling, orbit, cut and FX order are preserved. Managed release requires an admitted loop carrier; ordinary voices retain their stock gate rather than acquiring two final gates.

Close seals only this ingress and releases its exact owned responder handles. Ordinary protected and legacy loop playback remain available. A failed seal does not suppress independent handle cleanup; uncertain or replaced ownership is retained explicitly and never removed by name. Prepared native programs still require their own start/end notifications and retirement.