SPB Git

Repository Public

DeckVoice.swift 22.9 KB 483 lines swift

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
Files main
Menu

Theme