SPB Git

Repository Public

deck-engine.md 16.1 KB

# Deck engine

A deck in ORIX DJ has two halves. DeckVoice runs on the render thread and turns a decoded track into audio. DJEngine holds the deck model on the control side (cue points, hot cues, loops, sync, quantize) and converts every request into timestamped events. This document covers both, plus TrackBuffer, the in-memory track format. The queueing mechanism between the two halves is described in audio-engine.md; what happens to the deck signal afterwards is in mixer.md.

Sources:

There are four decks (deckCount = 4), lettered A to D.

flowchart TD
    F["Audio file"] --> L["TrackBuffer.load (AVAudioFile, background queue)"]
    L --> TB["TrackBuffer: planar float32 stereo, file sample rate"]
    TB --> AN["TrackAnalyzer: grid, key, loudness"]
    AN --> M["DJEngine deck model: grid, cue, hot cues, loop, sync"]
    M -->|"ControlEvent: setTrack, play, seek, rate, loop"| V["DeckVoice (render thread)"]
    TB -->|"read only"| V
    V --> D{"key lock or key shift, and not reverse, not braking"}
    D -->|no| DIR["Direct path: Catmull-Rom read at position"]
    D -->|yes| WS["TimeStretcher (WSOLA) into FIFO"]
    WS --> RS["Catmull-Rom read of the FIFO at pitch ratio"]
    DIR --> DC["emit: de-click offset"]
    RS --> DC
    DC --> OUT["Deck output to channel strip"]
    V -->|"DeckRenderState snapshot, notices"| M

# TrackBuffer

TrackBuffer holds a whole track in memory as two planar arrays of 32-bit float (left, right) at the sample rate of the file. Nothing is streamed from disk during playback, which is what lets the render thread seek, loop and play backwards without I/O.

  • TrackBuffer.load(url:progress:isCancelled:) decodes with AVAudioFile in chunks of 131 072 frames on a background queue. It accepts whatever AVAudioFile can read and requires the processing format to be non-interleaved float32.
  • Mono files are copied to both channels. For files with more than two channels only the first two are kept (data[0] and data[1]).
  • The track is not resampled at load time. Conversion to the engine rate happens in the voice (rateRatio = track.sampleRate / engineRate).
  • Duration cap: TrackBuffer.maxSeconds = 150.0 * 60, that is 150 minutes. A longer file is refused with TrackLoadError.tooLong, whose message states the limit.
  • If a compressed file reports a length slightly above what decodes, the frames read so far are kept; the tail of the buffer stays zero.
  • Memory: byteSize = frameCount * 2 * MemoryLayout<Float>.size, i.e. 8 bytes per frame. The cost per minute and at the cap is tabulated in performance.md.

Lifetime: DJEngine.load stores the buffer in its retained dictionary and sends the pointer in a deckSetTrack event. The voice hands the previous buffer back through a releaseTrack notice, so a buffer is never freed on the render thread. A deck must be paused to be loaded or unloaded (load and unload return false otherwise; DJSession.load reports SessionError.deckBusy).

# DeckVoice

DeckVoice.render always writes the full block. When the deck is stopped or empty it emits zeros through the same de-click stage as audio. When it plays, it chooses one of two paths per block:

swift
let wantStretch = (keylock || pitchRatio != 1) && !reverse && !braking

Switching path resets the stretcher or takes over the stretcher's playhead, and flags a discontinuity for the de-click stage.

# Direct path

renderDirect advances a fractional source position by

text
step = rate * brakeFactor * pitchScale * rateRatio * direction

per output sample, where rate follows targetRate through a one-pole smoother with a 4 ms time constant, pitchScale is the key-shift ratio when key lock is off, and direction is −1 in reverse. Changing the rate on this path changes tempo and pitch together (varispeed).

Resampling. Each output sample is a 4-point Catmull-Rom cubic interpolation of the source (cubic), with zero padding outside the track. This single interpolator performs sample-rate conversion (for example a 44.1 kHz file on a 48 kHz engine), varispeed and reverse. There is no anti-aliasing low-pass anywhere in DeckVoice: when the step is greater than 1 (faster playback, upward key shift without key lock, or a file whose sample rate is higher than the engine's), content above the new Nyquist frequency folds back. The amount has not been measured.

What is tested on this path: unity playback of a 48 kHz file is identical to the source within 1e-6 (unityPlaybackIsTransparent); a 44.1 kHz 1 kHz sine plays at 1000 Hz within 0.02 Hz and within 0.01 dB (sampleRateConversionKeepsPitchAndDuration); rate 1.25 gives 1250 Hz within 0.05 Hz (varispeedChangesPitchAndSpeed); reverse playback matches the mirrored source within 1e-5 (reverseAndBrake). These tests use sines, sweeps and noise; they do not measure aliasing or interpolation loss near Nyquist.

# Stretched path (key lock and key shift)

TimeStretcher is a waveform-similarity overlap-add (WSOLA) time scaler working in the time domain. Its sizes are fixed at construction from the engine sample rate:

Constant Engine rate up to 60 kHz Above 60 kHz Meaning
frame 2048 4096 analysis frame, Hann window
hop 1024 (frame / 2) 2048 synthesis hop, 50 % overlap
tolerance 512 (frame / 4) 1024 search range either side of the ideal position

Note that these sizes are in source frames, while the choice between the two sets is made on the engine rate. At 48 kHz with a 48 kHz file a frame is 42.7 ms and a hop 21.3 ms.

produce synthesises one hop:

  1. The ideal analysis position advances by alpha * hop per hop, where alpha is the time-scale factor.
  2. If the natural continuation of the previous frame (previousStart + hop) lies within tolerance of the ideal position, it is used as is. With alpha == 1 this is always the case, so the output equals the input.
  3. Otherwise the stretcher searches the 2 * tolerance + 1 candidate offsets around the ideal position for the segment most similar to the natural continuation: a cross-correlation (vDSP_conv) of the mono sum of both channels, normalised by the square root of the candidate's energy. Both channels use the offset found, so the stereo image is not shifted between channels.
  4. The chosen frame is windowed and overlap-added with the stored tail of the previous frame. The first frame after a reset has no tail and starts with unwindowed source.

renderStretched fills a FIFO of 6 * hop frames from the stretcher and reads it with the same Catmull-Rom interpolator at pitch * rateRatio frames per output sample:

Mode pitch alpha Result
Key lock on pitchRatio rate / pitchRatio tempo follows the rate, pitch follows only the key shift
Key lock off, key shift set rate * pitchRatio 1 / pitchRatio tempo follows the rate, pitch follows rate and key shift

pitchRatio is 2^(semitones / 12); the control range is ±12 semitones (keyShift in ScriptSchema). The playhead reported to the control side is the stretcher's continuation point minus what is still buffered in the FIFO.

What is tested: with key lock at rates 0.8 to 1.25 a 440 Hz sine stays within 0.5 Hz, the playhead advances at the rate within 0.06 s over 4 s, and the level stays within 1 dB (keyLockKeepsPitchWhileTempoChanges); key shifts of −5, +3, +7 and +12 semitones land within 0.2 % of the expected frequency without changing tempo (keyShiftTransposesWithoutChangingTempo); 120 BPM clicks at rate 1.05 arrive within 12 ms of their ideal times with no drift (keyLockPreservesBeatTiming). Measured pitch error and residual per rate are in performance.md.

# Key lock limitations

  • The method is single-band time-domain WSOLA. There is no transient detection, no phase vocoder and no formant handling. Clicks may move by a few milliseconds (the test allows 12 ms), and the benchmark shows a residual as high as 25.6 dB below a pure tone at rate 1.08. Nobody has listened to the result; the audible quality on music is not verified.
  • Key lock does not apply in reverse or during a brake: both force the direct path. In reverse with key lock on, the key shift is also ignored (pitchScale is 1 when keylock is set).
  • Loops on the stretched path wrap when the analysis position crosses the loop end (stretcher.shift), once per hop, with the seam cross-faded by the overlap-add. The wrap is therefore not sample-exact, and a loop shorter than about one hop times alpha may fail to wrap again by reading the code. The sample-exact loop test (loopIsSampleExact) runs on the direct path only.
  • The final resampler has no anti-aliasing filter, as on the direct path.

# De-click

All output goes through emit. When a discontinuity is flagged (seek, pause, loop wrap on the direct path, path switch, track end, track change), the difference between the previous output sample and the new one is captured as an offset and faded out with a smoothstep curve over 4 ms (declickStep = 1 / (0.004 * engineRate)). The audio itself is not delayed or faded; a decaying offset is added to it. A start from settled silence is deliberately not smoothed, so a cue point on a kick starts on its exact sample.

Tested by transportIsClickFree: on an 80 Hz sine at amplitude 0.8, seek and pause produce no sample-to-sample step above 0.03.

# Loops, brake, reverse, end of track

  • Loops. setLoop requires the end to be more than 16 frames after the start. On the direct path the position wraps by exactly the loop length when it crosses the end (or the start, in reverse), keeping the fractional position. loopIsSampleExact checks a 2-beat loop at 120 BPM: successive passes are exactly 48 000 samples apart per two clicks.
  • Brake. brake(seconds:) decreases brakeFactor linearly from 1 to 0 over the given time (minimum 0.02 s), then pauses and raises brakeFinished. The BRAKE button in the deck view passes one beat at the clock tempo (60 / max(60, bpm) seconds).
  • Reverse. Plays backwards on the direct path; reaching frame 0 stops the deck and raises reachedEnd.
  • End of track. The voice stops, sets reachedEnd, and the render loop sends a trackEnded notice. trackEndStopsAndReports checks the trackEnd event.
  • Limits applied on the render thread. deckRate is clamped to 0.05…4 and deckPitch to 0.25…4. The control side is narrower: the rate parameter accepts 0.5…2, writing bpm clamps the resulting rate to 0.5…2, and the tempo fader in the interface covers ±8 % (ControlTargets.tempoRange = 0.08).

# Deck control in DJEngine

DJEngine keeps a DeckModel per deck under its lock and mirrors it into events. Positions are kept in source frames. Because a seek only takes effect when the render thread processes it, pushSeek stores a seekShadow (target frame and issue time) that livePosition returns until the render thread has caught up; this is what lets setCue or setHotcue be called right after a seek and see the new position.

Every transport and parameter call accepts an optional engine sample time (at:); the automation host uses it to schedule on exact samples (see automation.md).

# Cue and hot cues

  • On load the cue point is placed on the first beat of the grid when there is one, otherwise at 0, and the deck is seeked there.
  • cue(deck:) pauses and seeks to the cue point. setCue stores the current position, snapped to the nearest beat when quantize is on. In the deck view, CUE returns to the cue point and Option-click stores it.
  • There are 8 hot cues per deck (ScriptSchema.hotCueCount). setHotcue stores the snapped position; hotcue seeks to it and starts the deck if it was paused. If the deck is already playing with quantize on, the jump keeps the playhead's offset within the current beat, so the beat phase is preserved.
  • jump(deck:beats:) moves by a number of beats using the track grid, or the clock tempo when there is no grid.
  • Cue points and hot cues are stored in the library by DJSession.persistCues and restored on load (see persistence.md).

quantizedCuesAndHotCues checks that a hot cue set at 4.07 s on a 120 BPM grid is stored at exactly 4.0 s, and at 6.07 s with quantize off.

# Quantize

Quantize is on by default per deck. It affects setCue, setHotcue, loopIn, loopOut (nearest beat, snap), the start of beat loops and the phase-preserving hot cue jump. loop(deck:beats:) starts on the beat just passed, unless the playhead is more than 0.875 of the way to the next beat, in which case it starts on the next one. The loop length is beats * framesPerBeat, and a loop must be longer than 32 frames. scaleLoop halves or doubles the active loop and refuses lengths under 64 frames or beyond the end of the track. The interface offers loops of 1/4 to 16 beats.

# Master clock

DJEngine.service() runs on the scheduler thread every 4 ms in the application, and after every block offline. It maintains the master clock:

  • Master deck. An explicitly chosen deck (setMasterDeck) if it is playing and has a grid; otherwise the current master while it remains eligible; otherwise the first playing deck that has a grid.
  • Tempo. grid.bpm * rate of the master deck, or the free tempo (master.bpm, 20…400, default 120) when no deck qualifies.
  • Beat. The clock beat is extrapolated from an anchor and then locked to the master deck's grid: same beat phase and same bar phase (4 beats per bar, relative to the grid's downbeat). It never moves backwards (max(aligned, lastClockBeat)).
  • A clock event carries tempo and beat to the render thread, where the beat-synchronised effects use it (dsp.md).

masterClockFollowsTheMasterDeck checks that the clock reports 128 BPM within 1e-6 for a 128 BPM master, that its beat phase equals the deck's, and 136 BPM within 0.01 after the rate is set to 1.0625.

# Sync with phase bend

A deck with sync on that is not the master is steered in every service() call:

  1. Tempo ratio. ratio = clockBPM / grid.bpm, folded by octaves into 0.71…1.42 so that a half-time or double-time reading does not produce an extreme rate.
  2. Phase bend. When the deck plays and a master exists, the phase error is the fractional difference between the deck's beat and the clock's beat, wrapped to ±0.5 beat. If it exceeds 0.002 beat, bend = 1 - clamp(err * 0.6, -0.04, 0.04): the deck runs up to 4 % faster or slower until the phase closes.
  3. A deckRate event with ratio * bend is sent when either value changed.

Starting a synced, quantized deck is also phase-aligned: play computes where the master will be at the start time (two device buffers ahead when live) and issues a timed seek so that the deck starts on the same beat fraction.

Sync requires a beat grid on both decks; it aligns beats, not bars, and it relies on the analysed grid being correct (see analysis.md). syncMatchesTempoAndPhase syncs a 126 BPM click track to a 120 BPM master and requires the worst click offset to stay under 3 ms; the measured figure is in performance.md. The test uses synthetic click tracks with exact grids.

# How the interface exposes the deck

DeckView.swift drives the engine directly: play/pause, CUE, SYNC, MSTR (master deck), the ±8 % tempo fader, KEY LOCK, key shift buttons (one semitone per press, ±12), loop IN/OUT, beat loops, halve/double, EXIT/RELOOP, beat jumps, eight hot cue pads (Option-click clears), QUANT, REV, BRAKE, and beat-grid tools (shift by 5 ms, ÷2, ×2, set beat at playhead, set downbeat, TAP). The grid tools change the grid through DJSession.setGrid, which updates the engine and the library. The waveform displays are described in waveform.md.

Files main
Menu

Theme