Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX DJ9// File : Packages/ORIXDJCore/Sources/ORIXDJEngine/DeckVoice.swift10// Description : The render-thread half of a deck: varispeed playback with11// cubic interpolation, WSOLA time stretching for key lock12// and pitch shift, reverse, loops, brake, click-free13// transport. Allocation-free after init.14// Module : ORIXDJEngine15// Repository : https://git.spboucher.ai/orix-dj16// Created : 2026-11-2117// Last Modified : 2026-11-2118//19// =============================================================================20// AUTHOR & PROFESSIONAL AFFILIATION21// =============================================================================22//23// Author : Simon-Pierre Boucher24// Position : Professor of Finance25// Institution : Université du Québec en Outaouais (UQO)26// Department : Département des sciences administratives27// Organization : SP Boucher28//29// Website : https://spboucher.ai30// Git : https://git.spboucher.ai31//32// =============================================================================33// OFFICIAL CONTACT DIRECTORY34// =============================================================================35//36// General : info@spboucher.ai37// Professional : contact@spboucher.ai38// Direct : simon@spboucher.ai39// Research : research@spboucher.ai40// Development : dev@spboucher.ai41// Support : support@spboucher.ai42// Security/Admin : admin@spboucher.ai43// Notifications : notifications@spboucher.ai44//45// Preferred Contact: support@spboucher.ai46//47// =============================================================================48// COPYRIGHT & INTELLECTUAL PROPERTY49// =============================================================================50//51// Copyright (c) 202652// Simon-Pierre Boucher53//54// All rights reserved where applicable.55//56// This file is governed by the applicable project license,57// copyright notices, institutional agreements and relevant law.58//59// Unless expressly authorized by the applicable license or60// rights holder, copying, redistribution, sublicensing,61// publication and commercial exploitation are not permitted.62//63// Existing third-party rights and notices remain unaffected.64//65// =============================================================================66// CONFIDENTIALITY & SECURITY67// =============================================================================68//69// Classification : Public70// Distribution : Public repository; use is governed by the project license71// Security Contact : admin@spboucher.ai72//73// Access to this source does not independently grant permission74// to redistribute or disclose confidential materials.75//76// Do not embed credentials, private keys, access tokens,77// certificates or confidential personal information.78//79// =============================================================================80// LICENSE & MAINTENANCE81// =============================================================================82//83// License : None specified (no license file in this repository)84// Maintainer : Simon-Pierre Boucher85// Technical Contact: dev@spboucher.ai86//87// =============================================================================88// END OF SP BOUCHER SOURCE HEADER89// =============================================================================9091import Accelerate92import Foundation9394/// Waveform-similarity overlap-add time scaler. Produces audio at the source sample rate, consuming the source `alpha`95/// times faster than real time while keeping its pitch. With alpha == 1 the output equals the input.96final class TimeStretcher {97 let frame: Int98 let hop: Int99 let tolerance: Int100 private let window: UnsafeMutablePointer<Float>101 private let tailL: UnsafeMutablePointer<Float>102 private let tailR: UnsafeMutablePointer<Float>103 private let workL: UnsafeMutablePointer<Float>104 private let workR: UnsafeMutablePointer<Float>105 private let searchMono: UnsafeMutablePointer<Float>106 private let templateMono: UnsafeMutablePointer<Float>107 private let correlation: UnsafeMutablePointer<Float>108 private let coarseTemplate: UnsafeMutablePointer<Float>109 private let coarseSearch: UnsafeMutablePointer<Float>110111 /// Next ideal analysis position, in source frames.112 private(set) var analysisPosition = 0.0113 /// Start of the frame used last.114 private(set) var previousStart = 0115 private var hasPrevious = false116 private var tailValid = false117 /// Number of frames in which a similarity search ran (diagnostics).118 private(set) var searches = 0119120 init(sampleRate: Double) {121 frame = sampleRate > 60000 ? 4096 : 2048122 hop = frame / 2123 tolerance = frame / 4124 window = .allocate(capacity: frame)125 for i in 0 ..< frame { window[i] = 0.5 - 0.5 * cosf(2 * .pi * Float(i) / Float(frame)) }126 tailL = .allocate(capacity: hop); tailR = .allocate(capacity: hop)127 tailL.initialize(repeating: 0, count: hop); tailR.initialize(repeating: 0, count: hop)128 workL = .allocate(capacity: frame); workR = .allocate(capacity: frame)129 workL.initialize(repeating: 0, count: frame); workR.initialize(repeating: 0, count: frame)130 searchMono = .allocate(capacity: hop + 2 * tolerance + 8); searchMono.initialize(repeating: 0, count: hop + 2 * tolerance + 8)131 templateMono = .allocate(capacity: hop); templateMono.initialize(repeating: 0, count: hop)132 correlation = .allocate(capacity: 2 * tolerance + 8); correlation.initialize(repeating: 0, count: 2 * tolerance + 8)133 coarseTemplate = .allocate(capacity: hop); coarseTemplate.initialize(repeating: 0, count: hop)134 coarseSearch = .allocate(capacity: hop + 2 * tolerance + 8); coarseSearch.initialize(repeating: 0, count: hop + 2 * tolerance + 8)135 }136137 deinit {138 window.deallocate(); tailL.deallocate(); tailR.deallocate(); workL.deallocate(); workR.deallocate()139 searchMono.deallocate(); templateMono.deallocate(); correlation.deallocate(); coarseTemplate.deallocate(); coarseSearch.deallocate()140 }141142 func reset(at position: Double) {143 analysisPosition = position; hasPrevious = false; tailValid = false144 }145146 /// Moves the analysis point by a whole distance (loop wrap) keeping the overlap tail, so the seam is cross-faded.147 func shift(by frames: Double) { analysisPosition += frames; hasPrevious = false }148149 /// Source position of the next output sample that `produce` will generate.150 var continuation: Double { hasPrevious ? Double(previousStart + hop) : analysisPosition }151152 @inline(__always) private static func copy(_ src: UnsafePointer<Float>, _ total: Int, from start: Int, count: Int, to dst: UnsafeMutablePointer<Float>) {153 // Zero-padded read outside the track.154 var s = start, n = count, d = dst155 if s < 0 { let z = min(n, -s); d.update(repeating: 0, count: z); d += z; n -= z; s = 0 }156 let avail = max(0, min(n, total - s))157 if avail > 0 { d.update(from: src + s, count: avail); d += avail; n -= avail }158 if n > 0 { d.update(repeating: 0, count: n) }159 }160161 private func mono(_ l: UnsafePointer<Float>, _ r: UnsafePointer<Float>, _ total: Int, from start: Int, count: Int, to dst: UnsafeMutablePointer<Float>) {162 Self.copy(l, total, from: start, count: count, to: dst)163 Self.copy(r, total, from: start, count: count, to: workR)164 vDSP_vadd(dst, 1, workR, 1, dst, 1, vDSP_Length(count))165 }166167 /// Synthesises `hop` output frames into `outL`/`outR` and advances the analysis position by `alpha * hop`.168 func produce(_ l: UnsafePointer<Float>, _ r: UnsafePointer<Float>, total: Int, alpha: Double, outL: UnsafeMutablePointer<Float>, outR: UnsafeMutablePointer<Float>) {169 let ideal = Int(analysisPosition.rounded())170 var chosen = ideal171 if hasPrevious {172 let natural = previousStart + hop173 if abs(natural - ideal) <= tolerance {174 // The natural continuation is inside the search window: it is the perfect match.175 chosen = natural176 } else {177 // Find the candidate around the ideal position most similar to the natural continuation.178 // Coarse pass on a 4:1 decimated signal, then a fine pass over the few lags around the best one:179 // about fifteen times cheaper than a full search, which matters when several decks search at once.180 mono(l, r, total, from: natural, count: hop, to: templateMono)181 let span = 2 * tolerance + 1182 mono(l, r, total, from: ideal - tolerance, count: hop + span - 1, to: searchMono)183 let factor = 4184 let coarseHop = hop / factor, coarseSpan = (span - 1) / factor + 1185 for i in 0 ..< coarseHop {186 let j = i * factor187 coarseTemplate[i] = templateMono[j] + templateMono[j + 1] + templateMono[j + 2] + templateMono[j + 3]188 }189 let coarseCount = coarseHop + coarseSpan190 for i in 0 ..< coarseCount {191 let j = i * factor192 coarseSearch[i] = j + 3 < hop + span - 1 ? searchMono[j] + searchMono[j + 1] + searchMono[j + 2] + searchMono[j + 3] : 0193 }194 vDSP_conv(coarseSearch, 1, coarseTemplate, 1, correlation, 1, vDSP_Length(coarseSpan), vDSP_Length(coarseHop))195 var energy: Float = 0196 vDSP_svesq(coarseSearch, 1, &energy, vDSP_Length(coarseHop))197 var best: Float = -.greatestFiniteMagnitude; var coarseBest = coarseSpan / 2198 for lag in 0 ..< coarseSpan {199 let score = correlation[lag] / sqrtf(energy + 1e-9)200 if score > best { best = score; coarseBest = lag }201 let out = coarseSearch[lag], inn = coarseSearch[lag + coarseHop]202 energy += inn * inn - out * out203 if energy < 0 { energy = 0 }204 }205 // Fine pass at full resolution.206 let lo = max(0, coarseBest * factor - factor), hi = min(span - 1, coarseBest * factor + factor)207 best = -.greatestFiniteMagnitude208 var bestLag = coarseBest * factor209 for lag in lo ... hi {210 var dot: Float = 0, e: Float = 0211 vDSP_dotpr(searchMono + lag, 1, templateMono, 1, &dot, vDSP_Length(hop))212 vDSP_svesq(searchMono + lag, 1, &e, vDSP_Length(hop))213 let score = dot / sqrtf(e + 1e-9)214 if score > best { best = score; bestLag = lag }215 }216 chosen = ideal - tolerance + bestLag217 searches += 1218 }219 }220 Self.copy(l, total, from: chosen, count: frame, to: workL)221 Self.copy(r, total, from: chosen, count: frame, to: workR)222 vDSP_vmul(workL, 1, window, 1, workL, 1, vDSP_Length(frame))223 vDSP_vmul(workR, 1, window, 1, workR, 1, vDSP_Length(frame))224 if tailValid {225 // Overlap-add with the second half of the previous frame (also cross-fades a loop seam).226 vDSP_vadd(workL, 1, tailL, 1, outL, 1, vDSP_Length(hop))227 vDSP_vadd(workR, 1, tailR, 1, outR, 1, vDSP_Length(hop))228 } else {229 // First frame after a reset: there is no previous tail, so start with the unwindowed source.230 Self.copy(l, total, from: chosen, count: hop, to: outL)231 Self.copy(r, total, from: chosen, count: hop, to: outR)232 }233 tailValid = true234 tailL.update(from: workL + hop, count: hop); tailR.update(from: workR + hop, count: hop)235 previousStart = chosen; hasPrevious = true236 analysisPosition += alpha * Double(hop)237 }238}239240/// One deck on the render thread. All methods are render-thread only.241final class DeckVoice {242 let engineRate: Double243 private let stretcher: TimeStretcher244245 // Track (owned by the control plane; swapped through events).246 private(set) var trackRef: Unmanaged<TrackBuffer>?247 private var srcL: UnsafePointer<Float>?248 private var srcR: UnsafePointer<Float>?249 private(set) var frames = 0250 private var rateRatio = 1.0251252 // Transport.253 private(set) var position = 0.0254 private(set) var playing = false255 var targetRate = 1.0256 private var rate = 1.0257 var reverse = false258 var keylock = false259 /// 2^(semitones / 12).260 var pitchRatio = 1.0261 private(set) var loopStart = 0.0262 private(set) var loopEnd = 0.0263 private(set) var loopActive = false264 private var brakeFactor = 1.0265 private var brakeStep = 0.0266 /// Set when the playhead ran off the end; cleared by the owner.267 var reachedEnd = false268 /// Set when a brake finished; cleared by the owner.269 var brakeFinished = false270271 // Stretch path.272 private var stretching = false273 private let fifoCapacity: Int274 private let fifoL: UnsafeMutablePointer<Float>275 private let fifoR: UnsafeMutablePointer<Float>276 private var fifoCount = 0277 private var fifoRead = 1.0278 private var lastAlpha = 1.0279280 // Click suppression: the step at a discontinuity is cancelled by a decaying offset.281 private var lastL: Float = 0282 private var lastR: Float = 0283 private var offsetL: Float = 0284 private var offsetR: Float = 0285 private var declick: Float = 0286 private var pendingDiscontinuity = false287 private let declickStep: Float288 private let rateSmoothing: Double289290 init(engineRate: Double) {291 self.engineRate = engineRate292 stretcher = TimeStretcher(sampleRate: engineRate)293 fifoCapacity = stretcher.hop * 6294 fifoL = .allocate(capacity: fifoCapacity); fifoR = .allocate(capacity: fifoCapacity)295 fifoL.initialize(repeating: 0, count: fifoCapacity); fifoR.initialize(repeating: 0, count: fifoCapacity)296 declickStep = 1 / Float(0.004 * engineRate)297 rateSmoothing = 1 - exp(-1 / (0.004 * engineRate))298 }299300 deinit { fifoL.deallocate(); fifoR.deallocate() }301302 // MARK: Control303304 /// Installs a track and returns the previous one for release off the render thread.305 func setTrack(_ ref: Unmanaged<TrackBuffer>?) -> Unmanaged<TrackBuffer>? {306 let old = trackRef307 trackRef = ref308 if let ref {309 // The control plane keeps the buffer alive until the render thread hands it back.310 let t = ref.takeUnretainedValue()311 srcL = UnsafePointer(t.left); srcR = UnsafePointer(t.right); frames = t.frameCount; rateRatio = t.sampleRate / engineRate312 } else { srcL = nil; srcR = nil; frames = 0 }313 playing = false; position = 0; loopActive = false; brakeFactor = 1; brakeStep = 0; reachedEnd = false314 stretching = false; fifoCount = 0; fifoRead = 1315 pendingDiscontinuity = true316 return old317 }318319 func play() {320 guard srcL != nil, !playing else { return }321 if !reverse, position >= Double(frames) { position = 0 }322 playing = true; brakeFactor = 1; brakeStep = 0; rate = targetRate323 restartStretch()324 // A start from settled silence is sample-exact and unsmoothed: a cue point on a kick must punch, and325 // scheduled starts must land on the exact sample. Only a start over a still-decaying tail is corrected.326 pendingDiscontinuity = declick > 0 || lastL != 0 || lastR != 0327 }328329 func pause() {330 guard playing else { return }331 playing = false332 position = playhead333 pendingDiscontinuity = true334 }335336 func seek(_ frame: Double) {337 position = min(max(0, frame), Double(frames))338 reachedEnd = false339 restartStretch()340 pendingDiscontinuity = true341 }342343 func setLoop(start: Double, end: Double) {344 guard end > start + 16 else { return }345 loopStart = max(0, start); loopEnd = min(Double(frames), end); loopActive = true346 }347348 func clearLoop() { loopActive = false }349350 /// Slows down to a stop over `seconds`, then pauses.351 func brake(seconds: Double) {352 guard playing else { return }353 brakeStep = 1 / max(0.02, seconds) / engineRate354 if stretching { position = playhead; stretching = false; pendingDiscontinuity = true }355 }356357 private func restartStretch() {358 stretcher.reset(at: position); fifoCount = 0; fifoRead = 1; stretching = false359 }360361 /// Source position of the audio leaving the deck now.362 var playhead: Double {363 guard stretching else { return position }364 let buffered = max(0, Double(fifoCount) - fifoRead)365 return stretcher.continuation - buffered * lastAlpha366 }367368 var isLoaded: Bool { srcL != nil }369 /// Effective speed relative to the original (for the tempo display).370 var currentRate: Double { rate * brakeFactor }371372 // MARK: Render373374 @inline(__always) private func cubic(_ p: UnsafePointer<Float>, _ count: Int, _ x: Double) -> Float {375 let i = Int(x.rounded(.down)); let f = Float(x - Double(i))376 if i >= 1, i < count - 2 {377 let a = p[i - 1], b = p[i], c = p[i + 1], d = p[i + 2]378 // Catmull-Rom.379 return b + 0.5 * f * (c - a + f * (2 * a - 5 * b + 4 * c - d + f * (3 * (b - c) + d - a)))380 }381 @inline(__always) func at(_ k: Int) -> Float { k >= 0 && k < count ? p[k] : 0 }382 let a = at(i - 1), b = at(i), c = at(i + 1), d = at(i + 2)383 return b + 0.5 * f * (c - a + f * (2 * a - 5 * b + 4 * c - d + f * (3 * (b - c) + d - a)))384 }385386 /// Renders `n` frames. Always writes the whole range (silence when stopped).387 func render(_ outL: UnsafeMutablePointer<Float>, _ outR: UnsafeMutablePointer<Float>, _ n: Int) {388 guard let l = srcL, let r = srcR, playing else {389 for i in 0 ..< n { emit(0, 0, outL, outR, i) }390 return391 }392 let braking = brakeStep > 0393 let wantStretch = (keylock || pitchRatio != 1) && !reverse && !braking394 if wantStretch != stretching {395 if wantStretch { stretcher.reset(at: position); fifoCount = 0; fifoRead = 1 } else { position = playhead }396 stretching = wantStretch397 pendingDiscontinuity = true398 }399 if stretching { renderStretched(l, r, outL, outR, n) } else { renderDirect(l, r, outL, outR, n) }400 }401402 @inline(__always) private func emit(_ xl: Float, _ xr: Float, _ outL: UnsafeMutablePointer<Float>, _ outR: UnsafeMutablePointer<Float>, _ i: Int) {403 if pendingDiscontinuity {404 // lastL is the previous output including any offset still decaying, so the step is fully cancelled.405 offsetL = lastL - xl; offsetR = lastR - xr406 declick = 1; pendingDiscontinuity = false407 }408 var yl = xl, yr = xr409 if declick > 0 {410 let g = declick * declick * (3 - 2 * declick)411 yl += offsetL * g; yr += offsetR * g412 declick = max(0, declick - declickStep)413 }414 outL[i] = yl; outR[i] = yr415 lastL = yl; lastR = yr416 }417418 private func renderDirect(_ l: UnsafePointer<Float>, _ r: UnsafePointer<Float>, _ outL: UnsafeMutablePointer<Float>, _ outR: UnsafeMutablePointer<Float>, _ n: Int) {419 let end = Double(frames)420 let direction: Double = reverse ? -1 : 1421 for i in 0 ..< n {422 if !playing { emit(0, 0, outL, outR, i); continue }423 rate += (targetRate - rate) * rateSmoothing424 if brakeStep > 0 {425 brakeFactor -= brakeStep426 if brakeFactor <= 0 {427 brakeFactor = 1; brakeStep = 0; playing = false; brakeFinished = true; pendingDiscontinuity = true428 emit(0, 0, outL, outR, i); continue429 }430 }431 let step = rate * brakeFactor * pitchScale * rateRatio * direction432 emit(cubic(l, frames, position), cubic(r, frames, position), outL, outR, i)433 let before = position434 position += step435 if loopActive {436 if direction > 0, before < loopEnd, position >= loopEnd { position -= loopEnd - loopStart; pendingDiscontinuity = true }437 else if direction < 0, before >= loopStart, position < loopStart { position += loopEnd - loopStart; pendingDiscontinuity = true }438 }439 if position >= end, direction > 0 { position = end; playing = false; reachedEnd = true; pendingDiscontinuity = true }440 else if position <= 0, direction < 0 { position = 0; playing = false; reachedEnd = true; pendingDiscontinuity = true }441 }442 }443444 /// Without key lock a pitch shift is plain resampling; with key lock it is handled by the stretcher.445 private var pitchScale: Double { keylock ? 1 : pitchRatio }446447 private func renderStretched(_ l: UnsafePointer<Float>, _ r: UnsafePointer<Float>, _ outL: UnsafeMutablePointer<Float>, _ outR: UnsafeMutablePointer<Float>, _ n: Int) {448 let hop = stretcher.hop449 for i in 0 ..< n {450 if !playing { emit(0, 0, outL, outR, i); continue }451 rate += (targetRate - rate) * rateSmoothing452 // Pitch factor of the final resampler, and the time-scale factor that leaves the wanted speed.453 let pitch = keylock ? pitchRatio : rate * pitchRatio454 let alpha = rate / pitch455 lastAlpha = alpha456 // Keep at least three samples ahead of the read point for the interpolator.457 while fifoRead + 3 >= Double(fifoCount) {458 if fifoCount + hop > fifoCapacity {459 // Drop consumed samples, keeping one behind the read point.460 let drop = Int(fifoRead) - 1461 if drop > 0 {462 memmove(fifoL, fifoL + drop, (fifoCount - drop) * MemoryLayout<Float>.size)463 memmove(fifoR, fifoR + drop, (fifoCount - drop) * MemoryLayout<Float>.size)464 fifoCount -= drop; fifoRead -= Double(drop)465 }466 }467 if stretcher.analysisPosition >= Double(frames) + Double(stretcher.frame) {468 position = Double(frames); playing = false; reachedEnd = true; pendingDiscontinuity = true469 break470 }471 let before = stretcher.analysisPosition472 stretcher.produce(l, r, total: frames, alpha: alpha, outL: fifoL + fifoCount, outR: fifoR + fifoCount)473 fifoCount += hop474 if loopActive, before < loopEnd, stretcher.analysisPosition >= loopEnd { stretcher.shift(by: -(loopEnd - loopStart)) }475 }476 if !playing { emit(0, 0, outL, outR, i); continue }477 emit(cubic(fifoL, fifoCount, fifoRead), cubic(fifoR, fifoCount, fifoRead), outL, outR, i)478 fifoRead += pitch * rateRatio479 }480 position = playhead481 }482}483