DSP
The ORIXDSP module contains the signal-processing building blocks of ORIX DJ and its 18 effect units. It depends only on Foundation and Synchronization; the engine (ORIXDJEngine) uses it for the channel strips, the effect racks and the master limiter. This document describes the primitives, the contract every effect follows, the catalogue, each effect with its algorithm and its stated limits, where the racks sit in the signal path, and the measured CPU cost.
Sources:
Primitives.swiftEffectUnit.swiftEffectCatalog.swiftEffects/:EffectFactory,EffectSupport,Space,Modulation,Filters,Distortion,Dynamics,Rhythm,Noise- Tests:
EffectsTests.swift,EffectBenchmarkTests.swift - UI:
EffectsView.swift
Primitives
Everything in Primitives.swift is allocation-free after initialisation.
| Primitive | Description |
|---|---|
dbToLinear, linearToDB |
Gain conversion with a floor: silenceFloorDB = -60; at or below it a gain is exactly 0. |
BiquadCoefficients |
RBJ Audio EQ Cookbook designs normalised to a0 = 1: lowpass, highpass, bandpass (constant 0 dB peak), peaking, lowShelf, highShelf, allpass. Frequencies are clamped to 10 Hz … 0.49 × sample rate, Q to at least 0.05. magnitude(at:sampleRate:) evaluates the response. |
StereoBiquad |
Transposed direct form II, state held inline, state values below 1e-20 flushed to zero after each block. Used by the channel EQ and filters (mixer.md). |
OnePoleSmoother |
Exponential smoother with a time constant in milliseconds; next() per sample, advance(n) per block. |
LinearRamp |
Linear ramp to a target over a fixed number of samples; used for every mixer parameter. |
DelayLine |
Power-of-two mono delay line with integer reads and fractional reads by linear interpolation. |
SPSCQueue |
Bounded wait-free single-producer single-consumer ring; carries control events and notices (audio-engine.md). |
NoiseGenerator |
32-bit xorshift white noise in −1…1, deterministic for a given seed. |
Shared helpers in EffectSupport.swift:
sane(x)maps NaN to 0 and clamps to ±32, so a bad input sample cannot enter recursive state.flush(x)zeroes values below 1e-15 (denormal protection).softClip(x)is a Padé approximation of tanh, exactly ±1 beyond |x| ≥ 3; it bounds feedback loops.beatPhase,beatPhaseIncrementconvert the transport beat position into an LFO phase.CrossfadeTapreads an integer delay and renders a change of delay as a short cross-fade between the old and new read positions (no pitch glide). A new target is accepted only when the running cross-fade has finished.SmoothedSVFis a stereo state-variable filter in trapezoidal (TPT) form with low-pass, high-pass and band-pass modes. Cutoff (in the log domain) and Q are smoothed with a 15 ms time constant; targets are evaluated every 32 samples and interpolated per sample. Its response is the same 12 dB/octave bilinear response as the RBJ biquad, but its state stays well behaved while coefficients move.
The EffectUnit contract
EffectUnit is the base class of every effect. Subclasses implement processWet, which replaces the buffers with the fully wet signal; the base class does the rest.
- Threading.
initanddeinitrun off the audio thread. Once a unit has been handed to the render thread,setParameter,setMix,setEnabled,setTransport,renderandresetare called from that thread only, and none of them may allocate, lock or call into Objective-C. Hand-over and release are described in audio-engine.md. - Block size.
renderaccepts at mostmaxBlock = 4096frames. - Parameters. Values live in a preallocated array indexed like
descriptor.params.setParameterignores non-finite values and clamps to the catalogue range, then callsparameterChanged. - Wet/dry and bypass.
renderkeeps a copy of the dry input, callsprocessWet, and outputsdry + (wet - dry) * g. The gaingmoves towardsmixwhen the unit is enabled and towards 0 when it is disabled, at a fixed slope of one full scale per 12 ms (rampPerSample = 1 / (0.012 * sampleRate)). Enabling, disabling and mix changes are therefore cross-fades. - True bypass. When the unit is disabled and
ghas reached 0,renderdoes not touch the audio and callsobserveBypassedinstead, which lets a unit keep observing the signal. - Transport.
setTransport(bpm:beatPosition:)is called before each block with the master clock; tempo is accepted between 20 and 400 BPM. - Hooks.
willEnable(transition to enabled),didFadeOut(fade-out finished; no unit currently overrides it),reset(clear internal state).
Generic tests run on all 18 kinds (GenericEffectTests):
| Test | Requirement |
|---|---|
finiteAndBounded |
Defaults, each parameter at its minimum and maximum, all-minimum and all-maximum, at 48 kHz and 44.1 kHz: finite output, peak at most 12 for an input peaking at 0.6. |
survivesBadInput |
NaN, infinite and out-of-range parameters, NaN/infinite audio samples, NaN beat position: output finite afterwards, peak at most 40. |
disabledIsBitTransparent |
A disabled unit returns its input bit for bit, also after having been enabled and disabled again. |
enableDisableHasNoStep |
Toggling on a 100 Hz sine produces no sample-to-sample step beyond what the dry and steady wet signals contain (+0.01). |
blockSizeIndependent |
512-frame and 64-frame blocks give the same output within 2e-3 (0.05 for the gate, whose edge may land one sample apart). |
These tests are objective measurements on synthetic signals. Nobody has done listening tests of the effects.
EffectCatalog
EffectCatalog.all is the single table of effects: kind, display name, category (space, modulation, filter, dynamics, distortion, rhythm, generator), a summary, the default mix, and for each parameter an id, name, unit (ratio, hertz, decibels, beats, milliseconds, toggle, number), range, default, a logarithmic-layout flag and a help text. EffectFactory.make(_:sampleRate:) creates the unit for a kind.
The same table drives the rack interface (knobs, ranges, help), the ORIX Script schema (fx.<effect>.<param>, see effects-api.md), the generated reference documentation and the assistant context (ai-integration.md). Parameters with unit beats are converted with the transport tempo, so delay times and LFO rates follow the master clock.
Racks in the signal path
There are five racks of rackSlotCount = 8 slots: one per deck and one on the master. DJEngine.insertEffect allows one unit of each kind per rack and returns the existing slot if the kind is already present; a ninth insertion returns −1. Units are processed in slot order; moveEffect and removeEffect reorder slots through fxSwap events. bypassAllEffects (the panic event, used by the Bypass All button and the console's panic command) disables every unit in every rack.
flowchart LR
DV["DeckVoice"] --> TR["Trim"]
TR --> EQ["EQ and channel filters (StereoBiquad)"]
EQ --> CR["Channel rack: slots 1 to 8 in order"]
CR --> PF["Pre-fader cue tap"]
CR --> FA["Fader and crossfader"]
FA --> SUM["Master sum of 4 channels"]
SUM --> MRK["Master rack: slots 1 to 8 in order"]
MRK --> MV["Master volume"]
MV --> LIM["Master limiter (LimiterEffect)"]
LIM --> OUT["Output, meters, recording tap"]
CLK["Master clock: bpm and beat"] -.-> CR
CLK -.-> MRK
The channel rack sits after the EQ and filters and before the cue tap and the fader, so an effect is heard in the headphones and its tail is cut by the fader. The master rack sits after the crossfader and before the master volume and limiter. See mixer.md for the rest of the path.
The effects
Parameter ranges are those of the catalogue. "Stale reset" means the unit marks itself stale while bypassed and clears its buffers in the first block after it is enabled again.
Effect (EffectKind) |
Parameters (default) | Default mix | Algorithm | Limits stated in the code or shown by the tests |
|---|---|---|---|---|
reverb |
size (0.55), damping (0.45), predelay 0–200 ms (15), width (1) | 0.3 | Freeverb topology: per channel 8 parallel damped feedback combs and 4 series all-passes (gain 0.5), right channel detuned by 23 samples at 44.1 kHz, tunings scaled to the sample rate. Mono-summed input through a pre-delay CrossfadeTap. |
Feedback is 0.7 + 0.28 * size, below 1, so it is stable for every setting. Input is the mono sum. Stale reset: the tail does not survive a bypass and is cut by the 12 ms fade when disabled. The code comment gives an RT60 of about 0.6 s to about 11 s; the test only requires decay to be monotonic, RT60 to grow by at least 15 % per size step, above 0.2 s at size 0 and below 6 s at size 0.8. |
delay |
time 1/16–4 beats (0.5), feedback 0–0.95 (0.35), ping-pong (off) | 0.25 | Stereo delay with an integer number of samples per repeat, feedback, optional cross-feeding ping-pong (mono input into the left line). Length changes cross-fade between two taps over 30 ms. | Maximum 4 s. Integer delay, so repeats are exact scaled copies (test: first repeat on the expected sample, ratio between repeats within 2e-3 of the feedback). Stale reset. |
echo |
time (0.75 beat), feedback (0.5), tone 200–12 000 Hz (4000) | 0.35 | Delay loop with a one-pole low-pass and 2 * softClip(x / 2) saturation in the feedback path, so repeats get darker and are bounded at ±2. |
Maximum 4 s. Stale reset. Test: each repeat is at least 30 % less bright than the previous one. |
flanger |
rate 0.02–5 Hz (0.25), depth (0.7), feedback −0.95…0.95 (0.5) | 0.5 | Delay modulated between 0.8 and 6.8 ms by a raised-cosine LFO, linear-interpolated reads, saturated feedback; the right channel is a quarter cycle ahead. | Free-running LFO, not beat-synchronised. Lines keep recording while bypassed. |
phaser |
rate (0.4 Hz), depth (0.8), feedback 0–0.9 (0.5) | 0.5 | Six first-order all-pass stages per channel swept two octaves either side of 800 Hz, saturated feedback. The wet signal is the all-pass chain alone; notches appear when mixed with the dry signal. | Coefficients are evaluated every 16 samples and interpolated. At mix 1 there are no notches by construction. Free-running LFO. |
chorus |
rate 0.05–5 Hz (0.8), depth (0.5) | 0.5 | Three modulated taps at 9, 14 and 20 ms, a third of a cycle apart, summed with gain 0.577; right channel a quarter cycle later. | Above 1 Hz the excursion shrinks with the rate so the pitch deviation stays bounded. No feedback. Free-running LFO. |
distortion |
drive 0–36 dB (12), tone 500–16 000 Hz (8000) | 1 | tanh(g x) * 0.5 / tanh(0.5 g) followed by a one-pole low-pass. |
The compensation keeps a −6 dBFS peak at −6 dBFS for every drive; quieter material is pulled up towards that level. No oversampling, so harmonics above Nyquist alias. Symmetric clipper: odd harmonics only (test). |
bitcrusher |
bits 2–16 (8), downsample 1–40 (4) | 1 | Integer sample-and-hold followed by a mid-tread quantiser with exactly 2^bits codes. | Both parameters are deliberately unsmoothed. No anti-aliasing before the hold; aliasing is the effect. |
highpass |
cutoff 20–20 000 Hz (200), resonance 0.5–10 (0.707) | 1 | SmoothedSVF high-pass, 12 dB/octave. |
Gain at the cutoff equals Q (test: +12.04 dB at Q 4). |
lowpass |
cutoff (8000), resonance (0.707) | 1 | SmoothedSVF low-pass, 12 dB/octave. |
Same. |
bandpass |
centre (1000), resonance (1.2) | 1 | SmoothedSVF band-pass, unity gain at the centre, 6 dB/octave each side. |
Tested against the analogue response within 1 to 1.5 dB. |
tremolo |
rate 1/32–4 beats (0.25), depth (0.8), shape (0) | 1 | Gain 1 - depth * (1 - m) with m a raised cosine peaking on the beat; shape sharpens it towards a square. Phase is recomputed from the transport at each block start. |
A 1 ms smoother on the gain absorbs phase jumps. Follows the master clock, not the deck's own grid. |
autopan |
rate 1/32–8 beats (1), depth (1) | 1 | Beat-locked sine pan with a balance law: the channel moved away from is attenuated, the other stays at unity. | No boost; the signal gets quieter overall as it pans. |
gate |
rate 1/32–4 beats (0.25), duty 0.05–0.95 (0.5), depth (1) | 1 | Open for the first duty fraction of each cycle, attenuated by depth for the rest, with 1 ms smoothed edges. |
Edges may land one sample apart depending on block size (see blockSizeIndependent). |
compressor |
threshold −60–0 dB (−18), ratio 1–20 (4), attack 0.1–200 ms (10), release 10–2000 ms (150), make-up 0–24 dB (0) | 1 | Feed-forward: peak detector (instant attack, 10 ms decay) on the louder channel, static curve with a 6 dB soft knee, attack/release smoothing of the reduction in dB, make-up gain. One gain for both channels. | No look-ahead and no side-chain filter. Static curve tested within 1 dB. |
limiter |
ceiling −24–0 dB (−1), release 10–1000 ms (100) | 1 | Look-ahead brick-wall limiter: required gain per sample, sliding minimum over 5 ms (monotonic deque), exponential release, then a moving average over the same window, which turns each drop into a 5 ms linear ramp. A final clamp guards against rounding. | 5 ms latency, not compensated; meant to be used fully wet. Sample-peak detection, not true-peak. Test: output never exceeds ceiling + 0.1 dB after the enable fade; below the ceiling the unit is a pure 240-sample delay at 48 kHz. Also used as the master limiter. |
beatrepeat |
length 1/32–4 beats (0.25) | 1 | Records the input continuously, also while bypassed. On enable, the most recent length beats plus a pre-roll of up to 5 ms are frozen and looped; the end of each pass cross-fades into the pre-roll. |
Maximum 4 s. A new length takes effect at the next loop start and can only shorten the frozen slice. The slice is whatever preceded the enable instant; it is not aligned to the beat grid by the unit. Test: output exactly periodic within 1e-6. |
noise |
level −60–0 dB (−18), cutoff 100–16 000 Hz (1000), resonance (2) | 1 | Independent white noise per channel through a smoothed constant-peak-gain band-pass, added to the input. | A narrower band is quieter. The generators are seeded with constants, so the noise sequence is the same in every unit instance. |
Common behaviours worth knowing:
- Only the delay, echo, tremolo, auto-pan, gate and beat repeat follow the tempo. The flanger, phaser and chorus rates are in hertz.
- Tempo-following units use the master clock sent to the render thread, not the grid of the deck they sit on. A deck that is not synced to the master is processed with the master's tempo and phase.
- Reverb, delay and echo clear their buffers on the render thread after a bypass; see the caveats in audio-engine.md.
- No effect is oversampled.
CPU cost
Measured by orix-dj-bench bench (release build, Apple M5 Max, one unit, enabled at its default mix, white-noise input at amplitude 0.3, 4000 blocks of 512 frames at 48 kHz, wall-clock mean per block). One 512-frame block lasts 10 667 µs. Source: engine-benchmark.txt.
| Effect | µs per 512-frame block | Share of real time |
|---|---|---|
| reverb | 36.31 | 0.340 % |
| delay | 3.08 | 0.029 % |
| echo | 3.60 | 0.034 % |
| flanger | 8.05 | 0.075 % |
| phaser | 10.67 | 0.100 % |
| chorus | 11.92 | 0.112 % |
| distortion | 7.23 | 0.068 % |
| bitcrusher | 1.96 | 0.018 % |
| highpass | 3.12 | 0.029 % |
| lowpass | 3.10 | 0.029 % |
| bandpass | 3.00 | 0.028 % |
| tremolo | 3.10 | 0.029 % |
| autopan | 2.76 | 0.026 % |
| gate | 2.38 | 0.022 % |
| compressor | 4.07 | 0.038 % |
| limiter | 3.18 | 0.030 % |
| beatrepeat | 2.46 | 0.023 % |
| noise | 3.06 | 0.029 % |
These are means on one machine with a steady signal and fixed parameters; they do not include the cost of parameter sweeps or of the first block after a bypass. The test cpuCostPerEffect repeats the measurement in whatever build the tests run in and fails if any effect exceeds 20 % of real time; its table is printed to the test log and is not reproduced here. Full-engine figures, conditions and what was not measured are in performance.md; the test suite is described in testing.md.