SPB Git

Repository Public

DJEngine.swift 48.0 KB 944 lines swift

1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXDJEngine/DJEngine.swift3// Description: The control plane of the DJ engine: decks, transport, cues, loops, sync, quantize, mixer and effect racks,4//              the master beat clock. Thread-safe; converts every request into timestamped events for the RenderCore.5//              One parameter space (ParamAddress) serves the interface, MIDI and ORIX Script alike.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import CoreAudio10import Foundation11import ORIXAnalysis12import ORIXDSP13import ORIXScript1415/// What a deck knows about its loaded track.16public struct LoadedTrack: Sendable, Equatable {17    public var libraryID: Int64?18    public var url: URL?19    public var title: String20    public var artist: String21    public var duration: Double22    public var sampleRate: Double23    public var grid: BeatGrid?24    public var key: KeyEstimate?25    public var bpmConfidence: Double26    public var waveform: WaveformSummary?2728    public init(libraryID: Int64? = nil, url: URL? = nil, title: String, artist: String = "", duration: Double, sampleRate: Double, grid: BeatGrid? = nil,29                key: KeyEstimate? = nil, bpmConfidence: Double = 0, waveform: WaveformSummary? = nil) {30        self.libraryID = libraryID; self.url = url; self.title = title; self.artist = artist; self.duration = duration; self.sampleRate = sampleRate31        self.grid = grid; self.key = key; self.bpmConfidence = bpmConfidence; self.waveform = waveform32    }3334    public static func == (a: LoadedTrack, b: LoadedTrack) -> Bool {35        a.libraryID == b.libraryID && a.url == b.url && a.title == b.title && a.duration == b.duration && a.grid == b.grid && a.key == b.key36    }37}3839public struct LoopRegion: Sendable, Equatable {40    public init(start: Double, end: Double, active: Bool) { self.start = start; self.end = end; self.active = active }41    public var start: Double42    public var end: Double43    public var active: Bool44}4546/// A consistent view of one deck for the interface.47public struct DeckStatus: Sendable, Equatable {48    public init(index: Int) { self.index = index }49    public var index: Int50    public var track: LoadedTrack?51    public var playing = false52    /// Seconds from the start of the file.53    public var position = 0.054    public var rate = 1.055    public var trackBPM = 0.056    public var bpm = 0.057    /// Fractional beat index on the track grid (0 without a grid).58    public var beat = 0.059    public var keylock = false60    public var keyShift = 0.061    public var sync = false62    public var quantize = true63    public var reverse = false64    public var isMaster = false65    public var cuePoint = 0.066    public var hotcues: [Double?] = Array(repeating: nil, count: ScriptSchema.hotCueCount)67    public var loop: LoopRegion?68    public var peak: Float = 069    public var rms: Float = 070    public var remaining: Double { max(0, (track?.duration ?? 0) - position) }71    public var letter: String { deckLetters[index] }72}7374public struct EffectSlotStatus: Sendable, Equatable, Identifiable, Codable {75    public init(kind: EffectKind, enabled: Bool, mix: Float, values: [Float]) { self.kind = kind; self.enabled = enabled; self.mix = mix; self.values = values }76    public var id: String { kind.rawValue }77    public var kind: EffectKind78    public var enabled: Bool79    public var mix: Float80    public var values: [Float]81}8283/// A saved effect chain.84public struct EffectChain: Sendable, Equatable, Codable {85    public var name: String86    public var slots: [EffectSlotStatus]87    public init(name: String, slots: [EffectSlotStatus]) { self.name = name; self.slots = slots }88}8990public enum EngineEvent: Sendable, Equatable {91    case deck(Int, String)92    case devicesChanged93    case deviceLost(String)94}9596public struct ClockState: Sendable, Equatable {97    public init(beat: Double, bpm: Double, sampleTime: Int64, masterDeck: Int?) { self.beat = beat; self.bpm = bpm; self.sampleTime = sampleTime; self.masterDeck = masterDeck }98    public var beat: Double99    public var bpm: Double100    public var sampleTime: Int64101    /// Deck driving the clock, nil when free-running.102    public var masterDeck: Int?103}104105public struct EngineConfiguration: Sendable, Equatable {106    public var sampleRate = 48000.0107    public var bufferFrames = 256108    public var deviceUID: String?109    public init() {}110}111112private struct DeckModel {113    var track: LoadedTrack?114    var frames = 0115    var playing = false116    var rate = 1.0117    var syncBend = 1.0118    var keylock = false119    var keyShift = 0.0120    var sync = false121    var quantize = true122    var reverse = false123    var cueFrame = 0.0124    var hotcues: [Double?] = Array(repeating: nil, count: ScriptSchema.hotCueCount)125    var loop: (start: Double, end: Double)?126    var loopActive = false127    /// A tape-stop is in progress: the deck's falling rate must not drive the clock or the synced decks.128    var braking = false129    var loopIn: Double?130    var lastBeatFloor = -Double.infinity131    /// Position requested by a seek the render thread has not executed yet, and the sample time it was issued at.132    var seekShadow: (frame: Double, issued: Int64)?133    var values: [String: Double] = [:]134}135136private struct RackSlot {137    var kind: EffectKind138    var enabled = false139    var mix: Float140    var values: [Float]141}142143public final class DJEngine: @unchecked Sendable {144    public private(set) var core: RenderCore145    public private(set) var configuration: EngineConfiguration146    /// Called on the service thread (or the caller's thread for synchronous transitions). Keep it short.147    public var onEvent: (@Sendable (EngineEvent) -> Void)?148    /// Resolves `deck.X.load("title")` and `loadNext()`. Returns an error message, or nil when the load was started.149    public var loadHandler: (@Sendable (_ deck: Int, _ query: String?) -> String?)?150151    private let lock = NSRecursiveLock()152    private let output = AudioOutput()153    private var decks = [DeckModel](repeating: DeckModel(), count: deckCount)154    private var racks = [[RackSlot]](repeating: [], count: deckCount + 1)155    private var mixer: [String: Double] = [:]156    private var mixerCurve = "smooth"157    private var explicitMaster: Int?158    private var masterDeck: Int?159    private var freeBPM = 120.0160    private var clockAnchorSample: Int64 = 0161    private var clockAnchorBeat = 0.0162    private var clockBPM = 120.0163    private var lastClockBeat = 0.0164    private var sentClockBPM = 0.0165    private var retained: [UnsafeMutableRawPointer: AnyObject] = [:]166    private var droppedEvents = 0167    public private(set) var isOffline: Bool168    private var offlineHostFrames: Int64 = 0169170    // MARK: Lifecycle171172    /// Creates an engine that is not attached to a device. Call `start` for live audio, or `renderOffline` in tests.173    public init(configuration: EngineConfiguration = .init()) {174        self.configuration = configuration175        core = RenderCore(sampleRate: configuration.sampleRate)176        isOffline = true177        for d in 0 ..< deckCount { for p in ScriptSchema.deckParams where p.writable { if let s = p.defaultValue.scalar { decks[d].values[p.key] = s } } }178        for p in ScriptSchema.mixerParams where p.writable { if let s = p.defaultValue.scalar { mixer[p.key] = s } }179    }180181    /// Opens the audio device and starts rendering. Safe to call again to change device, sample rate or buffer size.182    public func start() throws {183        lock.lock(); defer { lock.unlock() }184        let devices = AudioDevices.outputs()185        let chosen = devices.first { $0.uid == configuration.deviceUID } ?? devices.first { $0.isDefault } ?? devices.first186        guard let device = chosen else { throw AudioOutputError.noDevice }187        var rate = configuration.sampleRate188        if !device.sampleRates.contains(rate) { rate = device.sampleRates.contains(48000) ? 48000 : (device.sampleRates.first ?? device.currentSampleRate) }189        if rate != core.sampleRate { rebuildCore(sampleRate: rate) }190        configuration.sampleRate = rate191        try output.start(core: core, deviceID: device.id, bufferFrames: configuration.bufferFrames)192        isOffline = false193        applyRouting()194    }195196    public func stop() {197        lock.lock(); defer { lock.unlock() }198        output.stop(); isOffline = true199        for d in 0 ..< deckCount where decks[d].playing { decks[d].playing = false }200    }201202    public var isRunning: Bool { output.isRunning }203    public var currentDevice: AudioDeviceInfo? { lock.withLock { output.device } }204    public var outputChannelCount: Int { lock.withLock { output.isRunning ? output.channelCount : 2 } }205206    /// Changes device or format. Decks are unloaded when the sample rate changes (tracks are re-decoded by the caller).207    public func reconfigure(_ new: EngineConfiguration) throws {208        lock.lock(); defer { lock.unlock() }209        let wasRunning = output.isRunning210        output.stop()211        configuration = new212        if wasRunning { try start() } else if new.sampleRate != core.sampleRate { rebuildCore(sampleRate: new.sampleRate) }213    }214215    private func rebuildCore(sampleRate: Double) {216        // A new core starts clean; the model is replayed into it.217        core = RenderCore(sampleRate: sampleRate)218        retained.removeAll()219        clockAnchorSample = 0; clockAnchorBeat = lastClockBeat; sentClockBPM = 0220        for d in 0 ..< deckCount { decks[d].track = nil; decks[d].frames = 0; decks[d].playing = false; decks[d].loop = nil; decks[d].loopActive = false }221        replayModel()222    }223224    private func replayModel() {225        for d in 0 ..< deckCount {226            for (key, value) in decks[d].values { pushDeckParam(d, key, value, time: 0, ramp: 0, tracked: false) }227        }228        for (key, value) in mixer { pushMixerParam(key, value, time: 0, ramp: 0, tracked: false) }229        push(ControlEvent(.param, index: MixParam.crossfaderCurve.rawValue, a: Double(ScriptSchema.crossfaderCurves.firstIndex(of: mixerCurve) ?? 0)))230        let saved = racks231        racks = [[RackSlot]](repeating: [], count: deckCount + 1)232        for (r, slots) in saved.enumerated() {233            let rack = r == deckCount ? nil : r234            for s in slots {235                let i = insertEffect(s.kind, rack: rack)236                for (p, v) in s.values.enumerated() { setEffectParameter(rack: rack, slot: i, index: p, value: v) }237                setEffectMix(rack: rack, slot: i, s.mix); setEffectEnabled(rack: rack, slot: i, s.enabled)238            }239        }240    }241242    // MARK: Output routing243244    public struct Routing: Sendable, Equatable {245        public var masterLeft = 0, masterRight = 1246        /// -1 disables the dedicated cue output.247        public var cueLeft = -1, cueRight = -1248        /// Stereo-only devices: master in the left ear, cue in the right.249        public var splitCue = false250        public init() {}251    }252253    public private(set) var routing = Routing()254255    public func setRouting(_ r: Routing) { lock.withLock { routing = r; applyRouting() } }256257    private func applyRouting() {258        core.masterLeft.store(routing.masterLeft, ordering: .relaxed); core.masterRight.store(routing.masterRight, ordering: .relaxed)259        core.cueLeft.store(routing.cueLeft, ordering: .relaxed); core.cueRight.store(routing.cueRight, ordering: .relaxed)260        push(ControlEvent(.param, index: MixParam.splitCue.rawValue, a: routing.splitCue ? 1 : 0))261    }262263    // MARK: Event plumbing264265    private func push(_ e: ControlEvent) {266        if !core.events.push(e) { droppedEvents += 1 }267    }268269    public var droppedControlEvents: Int { lock.withLock { droppedEvents } }270271    /// Engine sample time "now": the end of the last rendered block.272    public var sampleTime: Int64 { core.engineState.read()[0].sampleTime }273274    public var renderState: EngineRenderState { core.engineState.read()[0] }275276    /// Renders without a device (tests, benchmarks, bounce). Returns the master channels.277    public func renderOffline(frames: Int, channels: Int = 2) -> [[Float]] {278        var out = [[Float]](repeating: [Float](repeating: 0, count: frames), count: channels)279        var done = 0280        let block = min(RenderCore.maxFrames, max(16, configuration.bufferFrames))281        let buffers = (0 ..< channels).map { _ in UnsafeMutablePointer<Float>.allocate(capacity: block) }282        defer { buffers.forEach { $0.deallocate() } }283        var pointers: [UnsafeMutablePointer<Float>?] = buffers.map { Optional($0) }284        while done < frames {285            let n = min(block, frames - done)286            pointers.withUnsafeBufferPointer { core.render(frameCount: n, channels: $0.baseAddress!, channelCount: channels) }287            for c in 0 ..< channels { out[c].withUnsafeMutableBufferPointer { ($0.baseAddress! + done).update(from: buffers[c], count: n) } }288            done += n289            service()290        }291        return out292    }293294    // MARK: Service (called regularly from the automation host thread, and after each offline block)295296    /// Drains render-thread notices, advances the master clock and maintains sync. Returns the clock.297    @discardableResult public func service() -> ClockState {298        lock.lock()299        var emitted: [EngineEvent] = []300        while let n = core.notices.pop() {301            guard let kind = NoticeKind(rawValue: n.kind) else { continue }302            let d = Int(n.deck)303            switch kind {304            case .releaseTrack, .releaseEffect: if let p = n.pointer { retained[p] = nil }305            case .trackEnded:306                if decks.indices.contains(d) { decks[d].playing = false; emitted.append(.deck(d, "trackEnd")); emitted.append(.deck(d, "pause")) }307            case .brakeFinished:308                if decks.indices.contains(d) { decks[d].playing = false; decks[d].braking = false; emitted.append(.deck(d, "pause")) }309            }310        }311        let states = core.deckStates.read()312        let now = core.engineState.read()[0].sampleTime313        let sr = core.sampleRate314315        // Master deck: an explicit choice, else the current one while it plays, else the first playing deck with a grid.316        func eligible(_ d: Int) -> Bool { states[d].playing && decks[d].track?.grid != nil }317        if let e = explicitMaster, eligible(e) { masterDeck = e }318        else if let m = masterDeck, eligible(m) {} else { masterDeck = (0 ..< deckCount).first(where: eligible) }319320        var beat = clockAnchorBeat + Double(now - clockAnchorSample) / sr * clockBPM / 60321        var bpm = freeBPM322        if let m = masterDeck, decks[m].braking {323            // Tape-stop on the master deck: the clock holds its tempo and runs on its own until the deck has stopped.324            bpm = clockBPM325        } else if let m = masterDeck, let grid = decks[m].track?.grid, let track = decks[m].track {326            bpm = grid.bpm * states[m].rate327            // Lock the clock to the master deck's grid: same beat phase, same bar phase.328            let deckBeat = grid.beat(at: states[m].position / track.sampleRate) - Double(grid.downbeatIndex)329            let bar = ORIXScriptLanguage.beatsPerBar330            let aligned = deckBeat + bar * ((beat - deckBeat) / bar).rounded()331            if decks[m].loopActive {332                // A looping master deck replays the same beats: the clock keeps running on its own at the deck's tempo,333                // so automations and followers go on in musical time (loop rolls, held loops).334            } else if aligned >= lastClockBeat {335                beat = aligned336            } else {337                // The deck is behind the clock (after a loop or a jump): never step back, run at half speed until it catches up.338                beat = lastClockBeat + (beat - lastClockBeat) * 0.5339            }340        }341        beat = max(beat, lastClockBeat)342        if !bpm.isFinite || bpm < 20 { bpm = freeBPM }343        clockAnchorSample = now; clockAnchorBeat = beat; clockBPM = bpm; lastClockBeat = beat344        if abs(bpm - sentClockBPM) > 1e-6 || now % 4096 < 512 {345            push(ControlEvent(.clock, a: bpm, b: beat, time: now)); sentClockBPM = bpm346        }347348        // A synced deck that has become the master keeps its tempo but drops the phase bend it was being steered with.349        if let m = masterDeck, decks[m].sync, decks[m].syncBend != 1 {350            decks[m].syncBend = 1351            push(ControlEvent(.deckRate, deck: m, a: decks[m].rate))352        }353        // Followers: match tempo, then steer the phase with a small rate bend.354        for d in 0 ..< deckCount where decks[d].sync && d != masterDeck {355            guard let grid = decks[d].track?.grid, grid.bpm > 0, let track = decks[d].track else { continue }356            var ratio = bpm / grid.bpm357            while ratio > 1.42 { ratio /= 2 }358            while ratio < 0.71 { ratio *= 2 }359            var bend = 1.0360            if states[d].playing, masterDeck != nil {361                let deckBeat = grid.beat(at: states[d].position / track.sampleRate)362                var err = (deckBeat - beat).truncatingRemainder(dividingBy: 1)363                if err > 0.5 { err -= 1 } else if err < -0.5 { err += 1 }364                if abs(err) > 0.002 { bend = 1 - min(0.04, max(-0.04, err * 0.6)) }365            }366            if abs(ratio - decks[d].rate) > 1e-9 || abs(bend - decks[d].syncBend) > 1e-6 {367                decks[d].rate = ratio; decks[d].syncBend = bend368                push(ControlEvent(.deckRate, deck: d, a: ratio * bend))369            }370        }371372        // Deck beat events.373        for d in 0 ..< deckCount {374            guard states[d].playing, let grid = decks[d].track?.grid, let track = decks[d].track else { decks[d].lastBeatFloor = -.infinity; continue }375            let f = grid.beat(at: states[d].position / track.sampleRate).rounded(.down)376            if decks[d].lastBeatFloor.isFinite, f != decks[d].lastBeatFloor { emitted.append(.deck(d, "beat")) }377            decks[d].lastBeatFloor = f378        }379        let clock = ClockState(beat: beat, bpm: bpm, sampleTime: now, masterDeck: masterDeck)380        let handler = onEvent381        lock.unlock()382        if let handler { for e in emitted { handler(e) } }383        return clock384    }385386    public var clock: ClockState {387        lock.withLock {388            let now = core.engineState.read()[0].sampleTime389            return ClockState(beat: clockAnchorBeat + Double(now - clockAnchorSample) / core.sampleRate * clockBPM / 60, bpm: clockBPM, sampleTime: now, masterDeck: masterDeck)390        }391    }392393    /// Engine sample time at which the master clock reaches `beat`.394    public func sampleTime(forBeat beat: Double) -> Int64 {395        lock.withLock { clockAnchorSample + Int64(((beat - clockAnchorBeat) * 60 / max(20, clockBPM) * core.sampleRate).rounded()) }396    }397398    public func setMasterDeck(_ deck: Int?) { lock.withLock { explicitMaster = deck } }399400    // MARK: Loading401402    /// Installs a decoded track on a deck. The deck must be paused.403    @discardableResult public func load(deck d: Int, buffer: TrackBuffer, info: LoadedTrack) -> Bool {404        lock.lock()405        guard decks.indices.contains(d), !decks[d].playing else { lock.unlock(); return false }406        let ref = Unmanaged.passUnretained(buffer).toOpaque()407        retained[ref] = buffer408        var model = decks[d]409        model.track = info; model.frames = buffer.frameCount; model.playing = false; model.loop = nil; model.loopActive = false; model.loopIn = nil410        model.hotcues = Array(repeating: nil, count: ScriptSchema.hotCueCount); model.syncBend = 1411        // The cue point starts on the first beat when there is a grid.412        model.cueFrame = (info.grid.map { max(0, $0.firstBeatSeconds) } ?? 0) * buffer.sampleRate413        if !model.sync { model.rate = 1 }414        decks[d] = model415        push(ControlEvent(.deckSetTrack, deck: d, pointer: ref))416        pushSeek(d, model.cueFrame)417        push(ControlEvent(.deckRate, deck: d, a: model.rate))418        let handler = onEvent419        lock.unlock()420        handler?(.deck(d, "loaded"))421        return true422    }423424    @discardableResult public func unload(deck d: Int) -> Bool {425        lock.withLock {426            guard decks.indices.contains(d), !decks[d].playing else { return false }427            decks[d].track = nil; decks[d].frames = 0; decks[d].loop = nil; decks[d].loopActive = false428            push(ControlEvent(.deckSetTrack, deck: d, pointer: nil))429            return true430        }431    }432433    /// Updates cue data restored from the library after a load.434    public func restore(deck d: Int, cuePoint: Double?, hotcues: [Double?]) {435        lock.withLock {436            guard decks.indices.contains(d), let track = decks[d].track else { return }437            if let cuePoint { decks[d].cueFrame = cuePoint * track.sampleRate }438            for (i, h) in hotcues.prefix(ScriptSchema.hotCueCount).enumerated() { decks[d].hotcues[i] = h.map { $0 * track.sampleRate } }439        }440    }441442    /// Replaces the beat grid of the loaded track (manual grid adjustment).443    public func setGrid(deck d: Int, _ grid: BeatGrid?) { lock.withLock { if decks.indices.contains(d) { decks[d].track?.grid = grid } } }444445    // MARK: Deck helpers446447    private func framesPerBeat(_ d: Int) -> Double? {448        guard let t = decks[d].track, let g = t.grid, g.bpm > 0 else { return nil }449        return 60 / g.bpm * t.sampleRate450    }451452    private func livePosition(_ d: Int) -> Double {453        if let shadow = decks[d].seekShadow {454            if core.engineState.read()[0].sampleTime <= shadow.issued { return shadow.frame }455            decks[d].seekShadow = nil456        }457        return core.deckStates.read()[d].position458    }459460    /// Queues a seek and remembers its target until the render thread has caught up.461    private func pushSeek(_ d: Int, _ frame: Double, time: Int64 = 0, tracked: Bool = false) {462        let now = core.engineState.read()[0].sampleTime463        if time <= now { decks[d].seekShadow = (frame, now) }464        push(ControlEvent(.deckSeek, deck: d, a: frame, time: time, tracked: tracked))465    }466467    /// Nearest grid beat, in frames.468    private func snap(_ d: Int, _ frame: Double) -> Double {469        guard decks[d].quantize, let t = decks[d].track, let g = t.grid else { return frame }470        return max(0, g.nearestBeatSeconds(to: frame / t.sampleRate) * t.sampleRate)471    }472473    private func emit(_ e: EngineEvent) { if let h = onEvent { h(e) } }474475    // MARK: Transport476477    @discardableResult public func play(deck d: Int, at time: Int64 = 0, tracked: Bool = false) -> String? {478        lock.lock()479        guard decks.indices.contains(d) else { lock.unlock(); return "No such deck." }480        guard decks[d].track != nil else { lock.unlock(); return "Deck \(deckLetters[d]) has no track loaded." }481        if decks[d].playing { lock.unlock(); return nil }482        var when = time483        // A synced, quantized deck starts in phase with the master deck.484        if decks[d].sync, decks[d].quantize, let m = masterDeck, m != d, let mg = decks[m].track?.grid, let mt = decks[m].track,485           let g = decks[d].track?.grid, let t = decks[d].track, let fpb = framesPerBeat(d) {486            let states = core.deckStates.read()487            let now = core.engineState.read()[0].sampleTime488            if when <= now { when = now + Int64(isOffline ? 0 : configuration.bufferFrames * 2) }489            let ahead = Double(max(0, when - now))490            let masterAt = states[m].position + ahead * states[m].rate * mt.sampleRate / core.sampleRate491            let masterBeat = mg.beat(at: masterAt / mt.sampleRate)492            let deckBeat = g.beat(at: states[d].position / t.sampleRate)493            var delta = (masterBeat - deckBeat).truncatingRemainder(dividingBy: 1)494            if delta > 0.5 { delta -= 1 } else if delta < -0.5 { delta += 1 }495            var target = states[d].position + delta * fpb496            if target < 0 { target += fpb }497            pushSeek(d, target, time: when)498        }499        decks[d].playing = true; decks[d].braking = false500        push(ControlEvent(.deckPlay, deck: d, time: when, tracked: tracked))501        lock.unlock()502        emit(.deck(d, "play"))503        return nil504    }505506    public func pause(deck d: Int, at time: Int64 = 0, tracked: Bool = false) {507        lock.lock()508        guard decks.indices.contains(d), decks[d].playing else { lock.unlock(); return }509        decks[d].playing = false510        push(ControlEvent(.deckPause, deck: d, time: time, tracked: tracked))511        lock.unlock()512        emit(.deck(d, "pause"))513    }514515    public func togglePlay(deck d: Int) { if lock.withLock({ decks.indices.contains(d) && decks[d].playing }) { pause(deck: d) } else { play(deck: d) } }516517    /// Pauses and returns to the start of the track.518    public func stopDeck(_ d: Int, at time: Int64 = 0) {519        pause(deck: d, at: time)520        lock.withLock { guard decks.indices.contains(d) else { return }; pushSeek(d, 0, time: time); decks[d].loopActive = false; push(ControlEvent(.deckLoopOff, deck: d, time: time)) }521    }522523    /// Jumps to the cue point and pauses.524    public func cue(deck d: Int, at time: Int64 = 0) {525        pause(deck: d, at: time)526        lock.withLock { guard decks.indices.contains(d) else { return }; pushSeek(d, decks[d].cueFrame, time: time) }527    }528529    public func setCue(deck d: Int) { lock.withLock { guard decks.indices.contains(d) else { return }; decks[d].cueFrame = snap(d, livePosition(d)) } }530531    /// Seeks to a position in seconds.532    public func seek(deck d: Int, seconds: Double, at time: Int64 = 0, tracked: Bool = false) {533        lock.withLock {534            guard decks.indices.contains(d), let t = decks[d].track else { return }535            pushSeek(d, max(0, seconds) * t.sampleRate, time: time, tracked: tracked)536        }537    }538539    /// Relative jump in beats (uses the track grid; falls back to the clock tempo).540    public func jump(deck d: Int, beats: Double, at time: Int64 = 0, tracked: Bool = false) {541        lock.withLock {542            guard decks.indices.contains(d), let t = decks[d].track else { return }543            let fpb = framesPerBeat(d) ?? 60 / max(20, clockBPM) * t.sampleRate544            let target = min(max(0, livePosition(d) + beats * fpb), Double(decks[d].frames))545            pushSeek(d, target, time: time, tracked: tracked)546        }547    }548549    // MARK: Loops and hot cues550551    @discardableResult public func loop(deck d: Int, beats: Double, at time: Int64 = 0, tracked: Bool = false) -> String? {552        lock.withLock {553            guard decks.indices.contains(d), let t = decks[d].track else { return "Deck \(deckLetters[d]) has no track loaded." }554            guard beats > 0 else { return "A loop needs a positive length." }555            let fpb = framesPerBeat(d) ?? 60 / max(20, clockBPM) * t.sampleRate556            let pos = livePosition(d)557            var start = pos558            if decks[d].quantize, let g = t.grid {559                // Start on the beat just passed, unless the next one is very close.560                let b = g.beat(at: pos / t.sampleRate)561                let chosen = b - b.rounded(.down) > 0.875 ? b.rounded(.up) : b.rounded(.down)562                start = max(0, g.seconds(atBeat: chosen) * t.sampleRate)563            }564            let end = min(Double(decks[d].frames), start + beats * fpb)565            guard end > start + 32 else { return "The loop does not fit before the end of the track." }566            decks[d].loop = (start, end); decks[d].loopActive = true567            push(ControlEvent(.deckLoop, deck: d, a: start, b: end, time: time, tracked: tracked))568            return nil569        }570    }571572    public func loopIn(deck d: Int) { lock.withLock { guard decks.indices.contains(d) else { return }; decks[d].loopIn = snap(d, livePosition(d)) } }573574    @discardableResult public func loopOut(deck d: Int, at time: Int64 = 0) -> String? {575        lock.withLock {576            guard decks.indices.contains(d), let start = decks[d].loopIn else { return "Deck \(deckLetters[d]): set a loop start first." }577            let end = snap(d, livePosition(d))578            guard end > start + 32 else { return "Deck \(deckLetters[d]): the loop end must be after the loop start." }579            decks[d].loop = (start, end); decks[d].loopActive = true580            push(ControlEvent(.deckLoop, deck: d, a: start, b: end, time: time))581            pushSeek(d, start, time: time)582            return nil583        }584    }585586    public func loopExit(deck d: Int, at time: Int64 = 0) {587        lock.withLock { guard decks.indices.contains(d) else { return }; decks[d].loopActive = false; push(ControlEvent(.deckLoopOff, deck: d, time: time)) }588    }589590    @discardableResult public func reloop(deck d: Int, at time: Int64 = 0) -> String? {591        lock.withLock {592            guard decks.indices.contains(d), let l = decks[d].loop else { return "Deck \(deckLetters[d]) has no previous loop." }593            decks[d].loopActive = true594            push(ControlEvent(.deckLoop, deck: d, a: l.start, b: l.end, time: time)); pushSeek(d, l.start, time: time)595            return nil596        }597    }598599    public func scaleLoop(deck d: Int, by factor: Double, at time: Int64 = 0) {600        lock.withLock {601            guard decks.indices.contains(d), decks[d].loopActive, let l = decks[d].loop else { return }602            let length = (l.end - l.start) * factor603            guard length >= 64, l.start + length <= Double(decks[d].frames) else { return }604            decks[d].loop = (l.start, l.start + length)605            push(ControlEvent(.deckLoop, deck: d, a: l.start, b: l.start + length, time: time))606        }607    }608609    public func setHotcue(deck d: Int, index: Int) {610        lock.withLock { guard decks.indices.contains(d), decks[d].hotcues.indices.contains(index), decks[d].track != nil else { return }; decks[d].hotcues[index] = snap(d, livePosition(d)) }611    }612613    public func clearHotcue(deck d: Int, index: Int) { lock.withLock { guard decks.indices.contains(d), decks[d].hotcues.indices.contains(index) else { return }; decks[d].hotcues[index] = nil } }614615    /// Jumps to a hot cue and plays. While playing with quantize on, the jump keeps the playhead's offset from the beat.616    @discardableResult public func hotcue(deck d: Int, index: Int, at time: Int64 = 0, tracked: Bool = false) -> String? {617        lock.lock()618        guard decks.indices.contains(d), decks[d].hotcues.indices.contains(index) else { lock.unlock(); return "No such hot cue." }619        guard let target = decks[d].hotcues[index] else { lock.unlock(); return "Deck \(deckLetters[d]): hot cue \(index + 1) is not set." }620        var frame = target621        let wasPlaying = decks[d].playing622        if wasPlaying, decks[d].quantize, let t = decks[d].track, let g = t.grid, let fpb = framesPerBeat(d) {623            let b = g.beat(at: livePosition(d) / t.sampleRate)624            frame += (b - b.rounded(.down)) * fpb625        }626        pushSeek(d, frame, time: time, tracked: tracked)627        lock.unlock()628        if !wasPlaying { return play(deck: d, at: time) }629        return nil630    }631632    public func brake(deck d: Int, seconds: Double, at time: Int64 = 0) {633        lock.withLock { guard decks.indices.contains(d), decks[d].playing else { return }; decks[d].braking = true; push(ControlEvent(.deckBrake, deck: d, a: seconds, time: time)) }634    }635636    // MARK: Parameters (one address space for the interface, MIDI and scripts)637638    private func pushDeckParam(_ d: Int, _ key: String, _ value: Double, time: Int64, ramp: Double, tracked: Bool) {639        let param: MixParam? = switch key {640        case "volume": .volume641        case "gain": .gain642        case "eq.low": .eqLow643        case "eq.mid": .eqMid644        case "eq.high": .eqHigh645        case "eq.lowMid": .eqLowMid646        case "filter": .filterKnob647        case "filter.highpass": .highpass648        case "filter.lowpass": .lowpass649        case "filter.resonance": .resonance650        case "cue": .cue651        case "assign": .assign652        default: nil653        }654        if let param { push(ControlEvent(.param, deck: d, index: param.rawValue, a: value, b: ramp, time: time, tracked: tracked)) }655    }656657    private func pushMixerParam(_ key: String, _ value: Double, time: Int64, ramp: Double, tracked: Bool) {658        let param: MixParam? = switch key {659        case "crossfader": .crossfader660        case "master.volume": .masterVolume661        case "master.limiter": .limiter662        case "cue.mix": .cueMix663        case "cue.volume": .cueVolume664        case "eqBands": .eqBands665        default: nil666        }667        if let param { push(ControlEvent(.param, index: param.rawValue, a: value, b: ramp, time: time, tracked: tracked)) }668    }669670    /// Sets any writable parameter. `value` must already be of the parameter's type; numbers are clamped to its range.671    /// Returns an error message when the address or the value is not acceptable.672    @discardableResult public func set(_ address: ParamAddress, _ value: Value, at time: Int64 = 0, rampSeconds: Double = 0, tracked: Bool = false) -> String? {673        lock.lock(); defer { lock.unlock() }674        switch address.area {675        case .deck:676            guard let d = address.deck, decks.indices.contains(d) else { return "No such deck." }677            if ["eq.lowMid", "assign"].contains(address.key), let x = value.scalar {678                let limited = address.key == "eq.lowMid" ? min(6, max(-26, x)) : min(2, max(0, x.rounded()))679                decks[d].values[address.key] = limited; pushDeckParam(d, address.key, limited, time: time, ramp: rampSeconds, tracked: tracked); return nil680            }681            guard let def = ScriptSchema.deckParam(address.key), def.writable else { return "'\(address)' cannot be set." }682            switch (address.key, value) {683            case let ("rate", .number(r)):684                decks[d].rate = min(def.max, max(def.min, r)); decks[d].syncBend = 1685                push(ControlEvent(.deckRate, deck: d, a: decks[d].rate, time: time, tracked: tracked))686            case let ("bpm", .number(b)):687                guard let g = decks[d].track?.grid, g.bpm > 0 else { return "Deck \(deckLetters[d]) has no analysed tempo, so its BPM cannot be set." }688                decks[d].rate = min(2, max(0.5, b / g.bpm)); decks[d].syncBend = 1689                push(ControlEvent(.deckRate, deck: d, a: decks[d].rate, time: time, tracked: tracked))690            case let ("keyShift", .number(s)):691                decks[d].keyShift = min(def.max, max(def.min, s))692                push(ControlEvent(.deckPitch, deck: d, a: pow(2, decks[d].keyShift / 12), time: time, tracked: tracked))693            case let ("keylock", .bool(b)): decks[d].keylock = b; push(ControlEvent(.deckKeylock, deck: d, a: b ? 1 : 0, time: time, tracked: tracked))694            case let ("reverse", .bool(b)): decks[d].reverse = b; push(ControlEvent(.deckReverse, deck: d, a: b ? 1 : 0, time: time, tracked: tracked))695            case let ("sync", .bool(b)):696                decks[d].sync = b697                if !b, decks[d].syncBend != 1 { decks[d].syncBend = 1; push(ControlEvent(.deckRate, deck: d, a: decks[d].rate, time: time)) }698            case let ("quantize", .bool(b)): decks[d].quantize = b699            case let ("cue", .bool(b)): decks[d].values["cue"] = b ? 1 : 0; pushDeckParam(d, "cue", b ? 1 : 0, time: time, ramp: 0, tracked: tracked)700            default:701                guard let x = value.scalar, value.type == def.type else { return "'\(address)' expects \(def.type)." }702                let clamped = min(def.max, max(def.min, x))703                decks[d].values[address.key] = clamped704                pushDeckParam(d, address.key, clamped, time: time, ramp: rampSeconds, tracked: tracked)705            }706            return nil707        case .mixer:708            if address.key == "eqBands", let x = value.scalar { mixer["eqBands"] = x; pushMixerParam("eqBands", x, time: time, ramp: 0, tracked: false); return nil }709            guard let def = ScriptSchema.mixerParam(address.key), def.writable else { return "'\(address)' cannot be set." }710            if address.key == "curve" {711                guard case let .string(s) = value, let i = ScriptSchema.crossfaderCurves.firstIndex(of: s) else { return "Unknown crossfader curve." }712                mixerCurve = s713                push(ControlEvent(.param, index: MixParam.crossfaderCurve.rawValue, a: Double(i), time: time, tracked: tracked)); return nil714            }715            guard let x = value.scalar, value.type == def.type else { return "'\(address)' expects \(def.type)." }716            let clamped = def.type == .bool ? x : min(def.max, max(def.min, x))717            mixer[address.key] = clamped718            pushMixerParam(address.key, clamped, time: time, ramp: rampSeconds, tracked: tracked)719            return nil720        case .master:721            guard address.key == "bpm", case let .number(b) = value else { return "'\(address)' cannot be set." }722            freeBPM = min(400, max(20, b)); return nil723        case .fx:724            guard let kind = address.effect else { return "No effect named." }725            let rack = address.deck726            let slot = insertEffect(kind, rack: rack)727            guard slot >= 0 else { return "The rack is full (\(rackSlotCount) effects)." }728            if address.key == "mix" { guard case let .number(m) = value else { return "mix expects a number." }; setEffectMix(rack: rack, slot: slot, Float(m), at: time, tracked: tracked); return nil }729            if address.key == "enabled" { guard case let .bool(b) = value else { return "enabled expects true or false." }; setEffectEnabled(rack: rack, slot: slot, b, at: time, tracked: tracked); return nil }730            let descriptor = EffectCatalog.descriptor(kind)731            guard let index = descriptor.index(of: address.key) else { return "'\(address)' does not exist." }732            let spec = descriptor.params[index]733            let raw: Double734            switch (value, spec.unit) {735            case let (.duration(span), .beats): raw = span.beats(atBPM: max(20, clockBPM))736            case let (.duration(span), .milliseconds): raw = span.seconds(atBPM: max(20, clockBPM)) * 1000737            case let (.bool(b), .toggle): raw = b ? 1 : 0738            default:739                guard let x = value.scalar else { return "'\(address)' expects a number." }740                raw = x741            }742            setEffectParameter(rack: rack, slot: slot, index: index, value: Float(raw), at: time, tracked: tracked)743            return nil744        }745    }746747    /// Current value of any parameter or property.748    public func value(of address: ParamAddress) -> Value? {749        lock.lock(); defer { lock.unlock() }750        switch address.area {751        case .deck:752            guard let d = address.deck, decks.indices.contains(d) else { return nil }753            let m = decks[d]754            if address.key == "eq.lowMid" { return .gain(m.values["eq.lowMid"] ?? 0) }755            if address.key == "assign" { return .number(m.values["assign"] ?? Double(d % 2)) }756            guard let def = ScriptSchema.deckParam(address.key) else { return nil }757            let st = core.deckStates.read()[d]758            let sr = m.track?.sampleRate ?? core.sampleRate759            switch address.key {760            case "rate": return .number(m.rate)761            case "bpm": return .number((m.track?.grid?.bpm ?? 0) * (st.playing ? st.rate : m.rate * m.syncBend))762            case "trackBpm": return .number(m.track?.grid?.bpm ?? 0)763            case "keyShift": return .number(m.keyShift)764            case "keylock": return .bool(m.keylock)765            case "sync": return .bool(m.sync)766            case "quantize": return .bool(m.quantize)767            case "reverse": return .bool(m.reverse)768            case "cue": return .bool((m.values["cue"] ?? 0) >= 0.5)769            case "position": return .duration(.seconds(st.position / sr))770            case "remaining": return .duration(.seconds(max(0, (m.track?.duration ?? 0) - st.position / sr)))771            case "duration": return .duration(.seconds(m.track?.duration ?? 0))772            case "beat": return .number(m.track?.grid?.beat(at: st.position / sr) ?? 0)773            case "playing": return .bool(m.playing)774            case "loaded": return .bool(m.track != nil)775            case "looping": return .bool(m.loopActive)776            case "level": return .gain(Double(linearToDB(st.peak)))777            case "key": return .string(m.track?.key?.camelot ?? "")778            case "title": return .string(m.track?.title ?? "")779            default:780                guard let x = m.values[address.key] else { return def.defaultValue }781                switch def.type { case .gain: return .gain(x); case .frequency: return .frequency(x); case .bool: return .bool(x >= 0.5); default: return .number(x) }782            }783        case .mixer:784            if address.key == "curve" { return .string(mixerCurve) }785            if address.key == "eqBands" { return .number(mixer["eqBands"] ?? 3) }786            if address.key == "master.level" { let s = core.engineState.read()[0]; return .gain(Double(linearToDB(max(s.masterPeakL, s.masterPeakR)))) }787            guard let def = ScriptSchema.mixerParam(address.key), let x = mixer[address.key] ?? def.defaultValue.scalar else { return nil }788            switch def.type { case .gain: return .gain(x); case .bool: return .bool(x >= 0.5); default: return .number(x) }789        case .master:790            switch address.key {791            case "bpm": return .number(clockBPM)792            case "beat": return .number(lastClockBeat)793            case "bar": return .number((lastClockBeat / ORIXScriptLanguage.beatsPerBar).rounded(.down))794            case "deck": return .string(masterDeck.map { deckLetters[$0] } ?? "")795            default: return nil796            }797        case .fx:798            guard let kind = address.effect, let def = ScriptSchema.fxParam(kind, address.key) else { return nil }799            let r = address.deck ?? deckCount800            guard racks.indices.contains(r) else { return nil }801            guard let slot = racks[r].first(where: { $0.kind == kind }) else { return def.defaultValue }802            if address.key == "mix" { return .number(Double(slot.mix)) }803            if address.key == "enabled" { return .bool(slot.enabled) }804            guard let i = EffectCatalog.descriptor(kind).index(of: address.key) else { return nil }805            let x = Double(slot.values[i])806            switch def.type {807            case .gain: return .gain(x)808            case .frequency: return .frequency(x)809            case .bool: return .bool(x >= 0.5)810            case .duration: return def.durationUnit == .beats ? .duration(.beats(x)) : .duration(.seconds(x / 1000))811            default: return .number(x)812            }813        }814    }815816    // MARK: Effect racks (rack nil = master)817818    private func rackIndex(_ rack: Int?) -> Int { rack ?? deckCount }819    private func rackEvent(_ rack: Int?) -> Int { rack ?? Int(masterRack) }820821    /// Adds an effect (one per kind and rack) and returns its slot, or -1 when the rack is full.822    @discardableResult public func insertEffect(_ kind: EffectKind, rack: Int?) -> Int {823        lock.lock(); defer { lock.unlock() }824        let r = rackIndex(rack)825        guard racks.indices.contains(r) else { return -1 }826        if let i = racks[r].firstIndex(where: { $0.kind == kind }) { return i }827        guard racks[r].count < rackSlotCount else { return -1 }828        let unit = EffectFactory.make(kind, sampleRate: core.sampleRate)829        let ref = Unmanaged.passUnretained(unit).toOpaque()830        retained[ref] = unit831        let d = EffectCatalog.descriptor(kind)832        racks[r].append(RackSlot(kind: kind, enabled: false, mix: d.defaultMix, values: d.params.map(\.defaultValue)))833        push(ControlEvent(.fxSet, deck: rackEvent(rack), index: Int32(racks[r].count - 1), pointer: ref))834        return racks[r].count - 1835    }836837    public func removeEffect(rack: Int?, slot: Int) {838        lock.lock(); defer { lock.unlock() }839        let r = rackIndex(rack)840        guard racks.indices.contains(r), racks[r].indices.contains(slot) else { return }841        // Bubble the slot to the end so the others keep their order, then clear it.842        for i in slot ..< racks[r].count - 1 { push(ControlEvent(.fxSwap, deck: rackEvent(rack), index: Int32(i | ((i + 1) << 8)))) }843        push(ControlEvent(.fxSet, deck: rackEvent(rack), index: Int32(racks[r].count - 1), pointer: nil))844        racks[r].remove(at: slot)845    }846847    public func moveEffect(rack: Int?, from: Int, to: Int) {848        lock.lock(); defer { lock.unlock() }849        let r = rackIndex(rack)850        guard racks.indices.contains(r), racks[r].indices.contains(from), racks[r].indices.contains(to), from != to else { return }851        var i = from852        while i != to {853            let j = to > i ? i + 1 : i - 1854            push(ControlEvent(.fxSwap, deck: rackEvent(rack), index: Int32(i | (j << 8))))855            racks[r].swapAt(i, j); i = j856        }857    }858859    public func setEffectEnabled(rack: Int?, slot: Int, _ on: Bool, at time: Int64 = 0, tracked: Bool = false) {860        lock.lock(); defer { lock.unlock() }861        let r = rackIndex(rack)862        guard racks.indices.contains(r), racks[r].indices.contains(slot) else { return }863        racks[r][slot].enabled = on864        push(ControlEvent(.fxEnable, deck: rackEvent(rack), index: Int32(slot), a: on ? 1 : 0, time: time, tracked: tracked))865    }866867    public func setEffectMix(rack: Int?, slot: Int, _ mix: Float, at time: Int64 = 0, tracked: Bool = false) {868        lock.lock(); defer { lock.unlock() }869        let r = rackIndex(rack)870        guard racks.indices.contains(r), racks[r].indices.contains(slot), mix.isFinite else { return }871        racks[r][slot].mix = min(1, max(0, mix))872        push(ControlEvent(.fxMix, deck: rackEvent(rack), index: Int32(slot), a: Double(racks[r][slot].mix), time: time, tracked: tracked))873    }874875    public func setEffectParameter(rack: Int?, slot: Int, index: Int, value: Float, at time: Int64 = 0, tracked: Bool = false) {876        lock.lock(); defer { lock.unlock() }877        let r = rackIndex(rack)878        guard racks.indices.contains(r), racks[r].indices.contains(slot), value.isFinite else { return }879        let spec = EffectCatalog.descriptor(racks[r][slot].kind).params880        guard spec.indices.contains(index) else { return }881        let v = min(spec[index].max, max(spec[index].min, value))882        racks[r][slot].values[index] = v883        push(ControlEvent(.fxParam, deck: rackEvent(rack), index: Int32(slot | (index << 8)), a: Double(v), time: time, tracked: tracked))884    }885886    public func rackStatus(_ rack: Int?) -> [EffectSlotStatus] {887        lock.withLock { racks[rackIndex(rack)].map { EffectSlotStatus(kind: $0.kind, enabled: $0.enabled, mix: $0.mix, values: $0.values) } }888    }889890    /// Replaces a rack with a saved chain.891    public func applyChain(_ chain: EffectChain, rack: Int?) {892        lock.lock(); defer { lock.unlock() }893        while !racks[rackIndex(rack)].isEmpty { removeEffect(rack: rack, slot: racks[rackIndex(rack)].count - 1) }894        for s in chain.slots.prefix(rackSlotCount) {895            let i = insertEffect(s.kind, rack: rack)896            guard i >= 0 else { continue }897            for (p, v) in s.values.enumerated() { setEffectParameter(rack: rack, slot: i, index: p, value: v) }898            setEffectMix(rack: rack, slot: i, s.mix); setEffectEnabled(rack: rack, slot: i, s.enabled)899        }900    }901902    /// Emergency: bypass every effect immediately.903    public func bypassAllEffects() {904        lock.lock(); defer { lock.unlock() }905        for r in racks.indices { for i in racks[r].indices { racks[r][i].enabled = false } }906        push(ControlEvent(.panic))907    }908909    // MARK: Status910911    public func deckStatus(_ d: Int) -> DeckStatus {912        lock.lock(); defer { lock.unlock() }913        let m = decks[d]914        let st = core.deckStates.read()[d]915        let sr = m.track?.sampleRate ?? core.sampleRate916        var s = DeckStatus(index: d)917        s.track = m.track; s.playing = m.playing; s.position = livePosition(d) / sr918        s.rate = st.playing ? st.rate : m.rate919        s.trackBPM = m.track?.grid?.bpm ?? 0; s.bpm = s.trackBPM * s.rate920        s.beat = m.track?.grid?.beat(at: s.position) ?? 0921        s.keylock = m.keylock; s.keyShift = m.keyShift; s.sync = m.sync; s.quantize = m.quantize; s.reverse = m.reverse922        s.isMaster = masterDeck == d923        s.cuePoint = m.cueFrame / sr924        s.hotcues = m.hotcues.map { $0.map { $0 / sr } }925        s.loop = m.loop.map { LoopRegion(start: $0.start / sr, end: $0.end / sr, active: m.loopActive) }926        s.peak = st.peak; s.rms = st.rms927        return s928    }929930    public var freeTempo: Double { lock.withLock { freeBPM } }931932    /// Opens or closes the recording tap on the master bus (used by `Recorder`).933    func setRecordTap(_ on: Bool) {934        lock.withLock {935            if on { core.recordRing.reset() }936            push(ControlEvent(.record, a: on ? 1 : 0))937        }938    }939}940941extension NSRecursiveLock {942    @discardableResult func withLock<T>(_ body: () throws -> T) rethrows -> T { lock(); defer { unlock() }; return try body() }943}944
Files main
Menu

Theme