Repository Public
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